### .desktop File Example

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/10-power-and-sessions.md

Example format for a .desktop file used for session discovery. Only 'Name' and 'Exec' are strictly required.

```ini
[Desktop Entry]
Name=GNOME
Exec=/usr/bin/gnome-session
Type=Application
X-Ubuntu-Session=ubuntu

```

--------------------------------

### Example greetd.toml Configuration

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/08-ipc-and-greetd.md

Shows how to configure custom environment variables and session wrappers for greetd.

```toml
[session]
environments = ["WAYLAND_DISPLAY=wayland-0", "XDG_CURRENT_DESKTOP=sway"]
session_wrapper = "sway"  # Prepended to session command
```

--------------------------------

### Install from AUR using yay

Source: https://github.com/notashelf/tuigreet/blob/master/README.md

Installs the precompiled binary version of greetd-tuigreet-fork from the Arch User Repository using the `yay` helper.

```bash
yay -S greetd-tuigreet-fork-bin
```

--------------------------------

### Start X11 Session with Gnome

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/10-power-and-sessions.md

Use this command to start an X11 session, specifically launching the GNOME desktop environment.

```bash
startx /usr/bin/env /usr/bin/gnome-session
```

--------------------------------

### Example Custom Session Configuration

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/10-power-and-sessions.md

A comprehensive TOML configuration file example for ~/.config/tuigreet/config.toml, setting default commands, session directories, wrappers, and session persistence.

```toml
# ~/.config/tuigreet/config.toml
[session]
command = "sway"  # Default command to run
sessions_dirs = ["/usr/share/wayland-sessions"]
xsessions_dirs = ["/usr/share/xsessions"]
session_wrapper = "systemd-cat -t sway"  # Prepend to Wayland sessions
xsession_wrapper = "startx /usr/bin/env"  # Prepend to X11 sessions

[remember]
session = true  # Remember last selected session
```

--------------------------------

### Example Gnome Session Wrapper Script

Source: https://github.com/notashelf/tuigreet/blob/master/README.md

Example bash script to set environment variables for Wayland Gnome session.

```bash
XDG_SESSION_TYPE=wayland dbus-run-session gnome-session
```

--------------------------------

### Render Custom Widget Example

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/11-ui-rendering.md

A basic example of how to render a custom widget with borders and a title using Ratatui.

```rust
use ratatui::{
    backend::Backend,
    layout::Constraint,
    text::Span,
    widgets::{Block, Borders, Paragraph},
    Frame,
};

fn render_custom_widget<B: Backend>(
    f: &mut Frame<B>,
    area: Rect,
    content: &str,
) {
    let block = Block::default()
        .borders(Borders::ALL)
        .title("Custom Widget");
    
    let paragraph = Paragraph::new(content)
        .block(block);
    
    f.render_widget(paragraph, area);
}
```

--------------------------------

### Full Session and Power Configuration Example

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/10-power-and-sessions.md

A TOML configuration file demonstrating settings for sessions, remembering user sessions, defining power actions (shutdown, reboot, suspend, hibernate), and keybindings.

```toml
[session]
command = "sway"
sessions_dirs = ["/usr/share/wayland-sessions"]
xsessions_dirs = ["/usr/share/xsessions"]
session_wrapper = "systemd-cat -t sway"
xsession_wrapper = "startx"
environments = ["WAYLAND_DISPLAY=wayland-0"]

[remember]
session = true
user_session = true

[power]
shutdown = "loginctl poweroff"
reboot = "loginctl reboot"
suspend = "loginctl suspend"
hibernate = "loginctl hibernate"
use_setsid = true

[keybindings]
command = 2    # F2 - edit command
sessions = 3   # F3 - select session
power = 12     # F12 - power menu
background = 4 # F4 - background switcher

```

--------------------------------

### dbus-run-session for PulseAudio

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/10-power-and-sessions.md

Configure a session wrapper to start a message bus session using dbus-run-session, often used for services like PulseAudio. This example uses bash as the command executed within the bus session.

```toml
[session]
session_wrapper = "dbus-run-session bash -c"
```

--------------------------------

### Example Library Usage in Rust

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/12-module-overview.md

Demonstrates how to load configuration, enumerate outputs, and parse a theme using the tuigreet library crates. Ensure necessary imports are present.

```rust
use tuigreet_config::parser::load_config;
use tuigreet_system::enumerate_outputs;
use tuigreet_theme::Theme;

let config = load_config(None, None)?;
let outputs = enumerate_outputs();
let theme = Theme::parse("text=white;border=cyan");
```

--------------------------------

### Example TOML Configuration

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/02-configuration-api.md

This is an example of a TOML configuration file for tuigreet. It covers general settings, display options, layout, user menus, secrets, keybindings, themes, background effects, outputs, and terminal settings.

```toml
[general]
debug = false
log_file = "/tmp/tuigreet.log"

[display]
show_time = true
time_format = "%Y-%m-%d %H:%M:%S"
greeting = "Welcome to the system!"
show_title = true
issue = false

[layout]
width = 60
window_padding = 2
container_padding = 1
prompt_padding = 1

[layout.widgets]
time_position = "top"
status_position = "bottom"

[remember]
username = true
session = false
user_session = true

[user_menu]
enabled = true
min_uid = 1000
max_uid = 60000

[secret]
mode = "characters"
characters = "*"

[keybindings]
command = 2
sessions = 3
power = 12
background = 4

[theme]
border = "white"
text = "green"
time = "blue"
container = "black"

[background]
kind = "doom"
fps = 30

[background.doom]
height = 6
spread = 2
top_color = "#9F2707"
middle_color = "#C78F17"
bottom_color = "#FFFFFF"

[[outputs]]
connector = "DP-1"
primary = true

[[outputs]]
connector = "HDMI-A-1"
enabled = false

[terminal]
cols = 120
rows = 40

```

--------------------------------

### TuiGreet TOML Configuration Example

Source: https://github.com/notashelf/tuigreet/blob/master/README.md

A comprehensive TOML configuration file for TuiGreet, demonstrating settings for display, layout, widgets, user menu, secrets, keybindings, background, sessions, power, and themes.

```toml
[display]
show_time = true
greeting = "Welcome to the system!"
align_greeting = "center"
issue = false

[layout]
width = 60
window_padding = 2
container_padding = 1
prompt_padding = 1

[layout.widgets]
time_position = "top"      # "top", "bottom", "default", "hidden"
status_position = "bottom" # "top", "bottom", "default", "hidden"

[remember]
username = true
session = false
user_session = true

[user_menu]
enabled = true
min_uid = 1000
max_uid = 60000

[secret]
mode = "characters"  # "hidden" or "characters"
characters = "*"

[keybindings]
command = 2     # F2
sessions = 3    # F3
background = 4  # F4
power = 12      # F12

[background]
kind = "doom"        # or "none" to disable
fps = 30

[background.doom]
height = 6           # 1-9, taller flames at higher values
spread = 2           # 0-4, horizontal jitter
top_color = "#9F2707"
middle_color = "#C78F17"
bottom_color = "#FFFFFF"

[background.matrix]
head_color = "#CCFFCC"
bright_color = "#33FF66"
dim_color = "#006622"
min_length = 6
max_length = 18
min_speed = 0.30     # rows per frame
max_speed = 1.10
mutate_chance = 0.02 # per-cell glyph shimmer probability

[session]
sessions_dirs = ["/usr/share/wayland-sessions", "/usr/share/xsessions"]
xsessions_dirs = []
environments = []

[power]
use_setsid = false

[theme]
border = "white"
text = "green"
time = "blue"
container = "black"
title = "cyan"
greet = "yellow"
prompt = "magenta"
input = "white"
action = "bright-blue"
button = "bright-red"

```

--------------------------------

### TOML Configuration for Output Settings

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/04-system-module.md

Example TOML configuration for defining output connectors and their properties, such as primary display and enablement status.

```toml
[[outputs]]
connector = "DP-1"
primary = true

[[outputs]]
connector = "HDMI-A-1"
enabled = false
```

--------------------------------

### Multi-Monitor Configuration (Sway on HDMI)

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/13-quick-reference.md

Set up TuiGreet for multi-monitor environments, specifying connectors and their enabled status. This example configures HDMI-A-1 as primary and DP-1 as disabled.

```toml
[[outputs]]
connector = "HDMI-A-1"
primary = true
enabled = true

[[outputs]]
connector = "DP-1"
enabled = false
```

--------------------------------

### Custom Desktop File Entry

Source: https://github.com/notashelf/tuigreet/blob/master/README.md

Example .desktop file entry for a custom Wayland session wrapper.

```plaintext
Name=Wayland Gnome
Exec=/path/to/my/wrapper.sh
```

--------------------------------

### Fluent Localization File Example (en-US)

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/05-locales-module.md

An example of a Fluent localization file (`.ftl`) defining messages in a key-value format for the en-US locale.

```ftl
# Example: en-US/messages.ftl
title-power = Power Options
title-sessions = Select Session
title-users = Select User
prompt-username = Username:
prompt-password = Password:
action-login = Login
action-cancel = Cancel

```

--------------------------------

### Systemd Session Wrapper

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/10-power-and-sessions.md

Configure a session wrapper to log session output to journald using systemd-cat. This example sets up logging for both Sway (Wayland) and generic X11 sessions.

```toml
[session]
session_wrapper = "systemd-cat -t sway"
xsession_wrapper = "systemd-cat -t X11"
```

--------------------------------

### Fluent Message Format Examples

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/05-locales-module.md

Illustrates different Fluent message formats, including simple messages, messages with variables, and messages with pluralization.

```ftl
message-id = Message content
message-with-var = Hello, { $name }!
message-with-plural = You have { $count ->
    [one] one file
   *[other] { $count } files
}

```

--------------------------------

### Setup Passwordless Sudo for Shutdown

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/13-quick-reference.md

Grant passwordless sudo access for the shutdown command to resolve 'Permission denied' errors. This method is less preferred than using loginctl.

```bash
echo "%wheel ALL=(ALL) NOPASSWD: /usr/bin/shutdown" | sudo tee /etc/sudoers.d/shutdown
```

--------------------------------

### Usage Example for MESSAGES

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/05-locales-module.md

Demonstrates how to access the global MESSAGES static instance. Dereferencing it triggers lazy initialization if it hasn't occurred yet.

```rust
use tuigreet_locales::MESSAGES;
use i18n_embed::LanguageLoader;

// First access triggers initialization
let loader = &*MESSAGES;
```

--------------------------------

### Get Translated Message

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/05-locales-module.md

Access the embedded messages using the `MESSAGES` loader. This example shows how to retrieve a specific fluent message by its ID.

```rust
use tuigreet_locales::MESSAGES;
use i18n_embed::LanguageLoader;

// First access initializes the loader
let loader = &*MESSAGES;

// Get a message (assumes a message with ID "greeting" exists in .ftl files)
if let Some(message) = loader.get_fluent_message("greeting", None) {
    println!("{}", message);
}
```

--------------------------------

### Rust TerminalConfig Invalid Reason Example

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/02-configuration-api.md

Demonstrates how to use the `invalid_reason` method on `TerminalConfig` to get a human-readable error string for inconsistent terminal settings. This is useful for debugging configuration issues.

```rust
let terminal_config = TerminalConfig {
    cols: Some(80),
    rows: None,
};

if let Some(reason) = terminal_config.invalid_reason() {
    eprintln!("Invalid terminal config: {}", reason);
    // Output: "Invalid terminal config: `terminal.rows` is set but `terminal.cols` is missing..."
}
```

--------------------------------

### Initialization Sequence

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/12-module-overview.md

Illustrates the step-by-step process of initializing the Greeter system, from parsing CLI arguments to setting up the terminal backend and entering the main event loop.

```text
main()
    ↓
Create Events system
    ↓
Greeter::new()
    ├── Parse CLI args (getopts)
    ├── Initialize logger (tracing)
    ├── Load config from files/env
    ├── Validate config
    ├── Apply theme from config
    ├── Apply terminal sizing (DRM)
    ├── Connect to greetd socket
    ├── Load sessions from desktop files
    └── Load users from NSS
    ↓
Setup crossterm backend
    ↓
Create ratatui Terminal
    ↓
run() - event loop
    ├── Check remembered session
    ├── Check single user auto-select
    ├── Spawn config watcher
    ├── Spawn IPC handler
    └── Main loop: events → render/keyboard/ipc
```

--------------------------------

### Greeter::new

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/06-greeter-struct.md

Creates a new Greeter instance. It initializes the greeter from CLI arguments and configuration files, setting up the environment for greeting operations.

```APIDOC
## new (async)

### Description
Creates a new `Greeter` instance, initializing from CLI arguments and config files.

### Method
`async fn new(events: Sender<Event>) -> Self`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use tokio::sync::mpsc;
use tuigreet::Greeter;

let (tx, _rx) = mpsc::channel(100);
let greeter = Greeter::new(tx).await;
```

### Response
#### Success Response
- **Self** (`Greeter`)

#### Response Example
None explicitly provided, returns a `Greeter` instance.
```

--------------------------------

### Spanish Translations Example

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/05-locales-module.md

Example translations for Spanish (`es`) locale, demonstrating how to provide localized strings for existing message IDs.

```ftl
title-power = Opciones de energía
prompt-username = Usuario:
prompt-password = Contraseña:

```

--------------------------------

### Creating a User Session with greetd-ipc

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/08-ipc-and-greetd.md

Demonstrates how to use the greetd_ipc crate to initiate a session and handle authentication responses.

```rust
use greetd_ipc::Request;
use tuigreet::Ipc;
use tokio::sync::RwLock;
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let mut ipc = Ipc::new();
    
    // Step 1: Create session for user
    let response = ipc.send(Request::CreateSession {
        username: "alice".to_string(),
    }).await;
    
    println!("Prompt: {}", response.auth_message);
    // Output: "Prompt: Password:"
    
    // Step 2: Send password
    let response = ipc.send(Request::Session {
        username: "alice".to_string(),
        session: "mypassword".to_string(),
    }).await;
    
    match response.auth_message_type {
        greetd_ipc::AuthMessageType::Success => println!("Logged in!"),
        greetd_ipc::AuthMessageType::Error => println!("Wrong password"),
        _ => println!("Another prompt: {}", response.auth_message),
    }
}
```

--------------------------------

### Load and Validate Configuration

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/00-index.md

Loads configuration from default paths or specified files, then validates it. Prints the theme if successful.

```rust
use tuigreet_config::parser::load_config;

let config = load_config(None, None)?;
config.validate(false)?;
println!("{:?}", config.theme);
```

--------------------------------

### Build and Test Commands

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/12-module-overview.md

Common commands for building the project in release mode, running all tests, and generating documentation.

```bash
cargo build --release
```

```bash
cargo test --all
```

```bash
cargo doc --open
```

--------------------------------

### Build Tuigreet from source

Source: https://github.com/notashelf/tuigreet/blob/master/README.md

Clones the repository, navigates into it, and builds Tuigreet in release mode using Cargo. The resulting binary can then be moved to a location in your PATH.

```bash
# Clone the repository and navigate to it
$ git clone https://github.com/NotAShelf/tuigreet && cd tuigreet

# Build in release mode
$ cargo build --release

# You may then move it to somewhere you can use it. If on NixOS, refer to above
# steps instead of trying to copy the binary.
# $ mv target/release/tuigreet /usr/local/bin/tuigreet
```

--------------------------------

### tuigreet Configuration & Debugging

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/13-quick-reference.md

Manage configuration loading, enable debug logging, specify log file locations, and use mock mode for testing. Dump configuration or list output devices.

```bash
tuigreet --config /etc/tuigreet/config.toml  # Load from file
```

```bash
tuigreet --no-config             # Skip config file loading
```

```bash
tuigreet --debug                 # Enable debug logging
```

```bash
tuigreet --log-file /tmp/greet.log
```

```bash
tuigreet --mock                  # Simulate auth (no greetd needed)
```

```bash
tuigreet --dump-config           # Print loaded config and exit
```

```bash
tuigreet --list-outputs          # List DRM monitors and exit
```

--------------------------------

### Display TOML Configuration Errors

Source: https://github.com/notashelf/tuigreet/blob/master/README.md

Examples of TOML parse errors with line numbers and source snippets to aid in debugging configuration files.

```plaintext
error[TOML001]: TOML parse error at line 2: extra =, expected nothing
  ┌─ config.toml:2:9
  │
2 │ width = = 123
  │         ^ extra =, expected nothing

error[TOML001]: TOML parse error at line 1: unclosed table, expected `]`
  ┌─ extra.toml:1:9
  │
1 │ [session
  │         ^ unclosed table, expected `]`

error[TOML001]: TOML parse error at line 2: key with no value, expected `=`
  ┌─ theme.toml:2:5
  │
2 │ key with space = true
  │     ^ key with no value, expected `=`
```

--------------------------------

### Create New Greeter Instance

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/06-greeter-struct.md

Asynchronously creates a new Greeter instance. It initializes the greeter from CLI arguments and configuration files, sets up event handling, and connects to the greetd socket.

```rust
pub async fn new(events: Sender<Event>) -> Self
```

```rust
use tokio::sync::mpsc;
use tuigreet::Greeter;

let (tx, _rx) = mpsc::channel(100);
let greeter = Greeter::new(tx).await;
```

--------------------------------

### register_panic_handler Function

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/07-main-entry-point.md

Installs a panic hook that restores the terminal to a normal state before unwinding, ensuring the panic message is not obscured by TUI drawing.

```APIDOC
## register_panic_handler Function

```rust
fn register_panic_handler()
```

### Description
Installs a panic hook that restores the terminal to normal state before unwinding.

### Behavior
- On panic, clears the screen
- Leaves alternate screen
- Disables raw mode
- Calls the original panic hook (prints backtrace)

This prevents the panic message from being obscured by TUI drawing.
```

--------------------------------

### Config Loading and Hot-Reload

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/12-module-overview.md

Describes how configuration is applied during startup and how changes are detected and re-applied via hot-reloading.

```text
Load TOML → Validate → Apply to Greeter fields
```

```text
File modified → ConfigWatcher detects → Send Event::Refresh → Re-render
```

--------------------------------

### Override tuigreet derivation in Nix

Source: https://github.com/notashelf/tuigreet/blob/master/README.md

An example Nix overlay to override the `tuigreet` package with a specific GitHub release source. Ensure to update the tag and hash values.

```nix
[
  (prev: {
    tuigreet = prev.tuigreet.overrideAttrs {
      src = prev.fetchFromGitHub {
        owner = "NotAShelf";
        repo = "tuigreet";
        tag = "0.10.2"; # update this with the tag you want to use
        hash = ""; # update this with the appropriate hash for your tag
      };

      # You will also need to overwrite the hash for cargo dependencies
      cargoHash = "" # update this with the appropriate hash
    };
  })
]
```

--------------------------------

### Configure greetd to use TuiGreet

Source: https://github.com/notashelf/tuigreet/blob/master/README.md

Set the 'command' in greetd's TOML configuration to launch TuiGreet. Ensure the 'vt' is set appropriately for terminal sessions.

```toml
[terminal]
vt = 1

[default_session]
command = "tuigreet --cmd sway"
user = "greeter"

```

--------------------------------

### Authentication Flow Overview

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/07-main-entry-point.md

Illustrates the sequence of operations during the user authentication process, from application startup to session creation.

```text
main()
├── Greeter::new() - load config, connect to greetd
├── remember check - auto-login if configured
├── single user check - auto-select if only one user
└── run() - event loop
    ├── wait for keyboard input
    ├── user types username
    ├── user types password
    ├── user presses enter
    ├── send CreateSession request to greetd
    ├── wait for greetd response
    ├── if success: exit(AuthStatus::Success)
    ├── if failure: display error, return to username
    ├── if cancel: exit(AuthStatus::Cancel)
    └── clean up and exit
```

--------------------------------

### Configure Session Environment Variables

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/10-power-and-sessions.md

Set custom environment variables for a session by adding them to the 'environments' list under the 'session' TOML section. These are merged with existing variables before the session starts.

```toml
[session]
environments = ["WAYLAND_DISPLAY=wayland-0", "XDG_SESSION_TYPE=wayland"]
```

--------------------------------

### List Available Sessions

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/10-power-and-sessions.md

Use this command to see all available desktop sessions on the system, categorized by Wayland and X11.

```bash
tuigreet --list-sessions
```

--------------------------------

### Configure Power Commands with Loginctl

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/13-quick-reference.md

Use loginctl for power commands as a preferred alternative to sudo, ensuring proper permissions.

```toml
[power]
shutdown = "loginctl poweroff"
```

--------------------------------

### Greeter Struct Initialization and Usage

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/06-greeter-struct.md

Demonstrates how to initialize the Greeter struct in an async context and access/modify its properties. Requires Tokio for async operations and `tuigreet` for the Greeter type.

```rust
use tuigreet::Greeter;
use tokio::sync::mpsc;

#[tokio::main]
async fn main() {
    let (tx, _rx) = mpsc::channel(100);
    
    let mut greeter = Greeter::new(tx).await;
    
    // Access configuration
    println!("Debug: {}", greeter.debug);
    println!("Username: {}", greeter.username.value);
    
    // Modify state
    greeter.mode = tuigreet_types::Mode::Password;
    greeter.buffer = "mypassword".to_string();
}
```

--------------------------------

### Run Function Signature

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/07-main-entry-point.md

The main event loop function that processes various events such as keyboard input, rendering requests, and IPC messages. It handles terminal setup, session management, and cleanup.

```rust
async fn run<B>(
    backend: B,
    mut greeter: Greeter,
    mut events: Events,
) -> Result<(), Box<dyn Error>>
where
    B: tui::backend::Backend,
```

--------------------------------

### Dump Loaded Configuration

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/13-quick-reference.md

Display the configuration that tuigreet has loaded, useful for verifying settings.

```bash
tuigreet --dump-config
```

--------------------------------

### Minimal Console Only Configuration

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/13-quick-reference.md

Use this configuration for a basic console-only TuiGreet experience.

```bash
tuigreet --cmd bash
```

--------------------------------

### Load Configuration from File

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/02-configuration-api.md

Loads configuration from a specified TOML file. Use this when you need to load configuration from a specific path, overriding other sources.

```rust
use std::path::Path;
use tuigreet_config::parser::load_config;

let config = load_config(
    Some(Path::new("/etc/tuigreet/config.toml")),
    None
)?;
```

--------------------------------

### List Available Displays

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/00-index.md

Lists all available display outputs that Tuigreet can utilize.

```bash
tuigreet --list-outputs
```

--------------------------------

### tuigreet Session & User Options

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/13-quick-reference.md

Configure default session commands, specify custom session directories, and manage user selection menus with UID constraints.

```bash
tuigreet --cmd sway          # Default session command
```

```bash
tuigreet --sessions /path    # Custom sessions directory
```

```bash
tuigreet --user-menu         # Enable user selection menu
```

```bash
tuigreet --user-menu-min-uid 1000
```

```bash
tuigreet --user-menu-max-uid 60000
```

--------------------------------

### Dark Theme with Animations Configuration

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/13-quick-reference.md

Configure a dark theme with specific colors for borders, text, and containers, along with enabling the matrix background animation at 30 FPS.

```toml
[theme]
border = "bright-cyan"
text = "bright-white"
container = "black"
input = "bright-white"
prompt = "bright-green"
action = "bright-blue"

[background]
kind = "matrix"
fps = 30
```

--------------------------------

### Configure Session Directories

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/13-quick-reference.md

Specify the directories where session files are located to resolve 'No sessions found' errors.

```toml
[session]
sessions_dirs = ["/usr/share/wayland-sessions"]
xsessions_dirs = ["/usr/share/xsessions"]
```

--------------------------------

### tuigreet (main binary) Exported Types, Functions, and Methods

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/12-module-overview.md

Exposes core types and functions for the main greeter application, including event handling, UI drawing, and power management operations.

```APIDOC
## tuigreet (main binary)

### Exported Types

- `pub struct Greeter { ... }`
- `pub enum Event { Render, Key(KeyEvent), Exit(AuthStatus), PowerCommand(PowerCommand), Refresh, SetFrameRate(u32) }`
- `pub enum PowerCommand { Shutdown, Reboot, Suspend, Hibernate }`
- `pub enum PowerPostAction { ReturnToGreeter, ClearScreen }`

### Exported Functions

- `impl Greeter { pub async fn new(events: Sender<Event>) -> Self; pub fn config(&self) -> &getopts::Matches }`
- `pub async fn handle(greeter: Arc<RwLock<Greeter>>, key: KeyEvent, ipc: Ipc) -> Result<(), Box<dyn Error>>`
- `pub async fn draw<B: Backend>(greeter: Arc<RwLock<Greeter>>, terminal: &mut Terminal<B>) -> Result<(), Box<dyn Error>>`
- `pub async fn run(greeter: &Arc<RwLock<Greeter>>, command: PowerCommand) -> PowerPostAction`
```

--------------------------------

### Parse and Apply Theme

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/11-ui-rendering.md

Parses a theme string from configuration and applies it to UI elements.

```rust
// Apply theme from config
let theme = Theme::parse(
    "border=cyan;text=white;input=bright-white;prompt=green;action=blue"
);

// Use in rendering
let border_style = theme.of(&[Themed::Border]);
let input_style = theme.of(&[Themed::Input]);
```

--------------------------------

### Enumerate System Outputs

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/00-index.md

Lists available system outputs, their connection status, and native resolution. Handles unknown resolutions gracefully.

```rust
use tuigreet_system::enumerate_outputs;

let outputs = enumerate_outputs();
for output in outputs {
    println!("{}: {} {}xவைக்", 
        output.connector,
        if output.connected { "connected" } else { "disconnected" },
        output.native_resolution.map(|(w, h)| format!("{}x{}", w, h))
            .unwrap_or("unknown".to_string())
    );
}
```

--------------------------------

### Dump Configuration

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/00-index.md

Dumps the current configuration of Tuigreet to standard output, paginated with 'less'.

```bash
tuigreet --dump-config | less
```

--------------------------------

### Session Lifecycle Flow

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/08-ipc-and-greetd.md

Illustrates the sequence of events from creating a session to successful login or error handling.

```text
CreateSession("alice")
    ↓
greetd responds with Password prompt
    ↓
Greeter switches to Password mode, shows prompt
    ↓
User types password
    ↓
User presses Enter
    ↓
Session({ username: "alice", session: "password_hash" })
    ↓
greetd validates password
    ↓
Success or Error response
    ↓
On Success: Execute session script, exit
On Error: Return to Password mode, retry
```

--------------------------------

### Configure Custom Session Wrappers

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/10-power-and-sessions.md

Define custom wrappers for general sessions and X11 sessions using TOML configuration.

```toml
[session]
session_wrapper = "dbus-run-session"
xsession_wrapper = "startx"
```

--------------------------------

### Power Command Execution

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/12-module-overview.md

Outlines the process for handling user-selected power actions, including execution.

```text
User selects power action → keyboard::handle() → Event::PowerCommand → power::run() → Execute command
```

--------------------------------

### Default Theme Behavior

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/03-theme-system.md

Shows how to create a default Theme. When no theme is specified, this results in the terminal's default colors being used.

```rust
use tuigreet_theme::Theme;

let theme = Theme::default();  // No colors specified
```

--------------------------------

### Handle Key Press Simulation

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/09-keyboard-and-events.md

Simulates user input for typing a username and pressing Enter. This demonstrates how individual key events are processed sequentially by the `keyboard::handle` function, updating the buffer and potentially changing the mode or sending IPC requests.

```rust
use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
use tuigreet_types::Mode;

// Simulate user typing "alice" + Enter
let keys = vec![
    KeyEvent::new(KeyCode::Char('a'), KeyModifiers::empty()),
    KeyEvent::new(KeyCode::Char('l'), KeyModifiers::empty()),
    KeyEvent::new(KeyCode::Char('i'), KeyModifiers::empty()),
    KeyEvent::new(KeyCode::Char('c'), KeyModifiers::empty()),
    KeyEvent::new(KeyCode::Char('e'), KeyModifiers::empty()),
    KeyEvent::new(KeyCode::Enter, KeyModifiers::empty()),
];

for key in keys {
    keyboard::handle(greeter, key, ipc).await?;
    // After each key:
    // - buffer is updated with character
    // - mode changes on Enter
    // - IPC request sent on CreateSession
}
```

--------------------------------

### Load and Validate Configuration with Error Handling

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/02-configuration-api.md

This Rust code demonstrates how to load a configuration file using `load_config` and then validate it. It includes specific error handling for parsing errors with context and general configuration errors.

```rust
use tuigreet_config::parser::load_config;
use tuigreet_config::ConfigError;
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    match load_config(None, None) {
        Ok(config) => {
            match config.validate(false) {
                Ok(warnings) => {
                    for warning in warnings {
                        eprintln!("Warning: {}", warning);
                    }
                    println!("Configuration loaded successfully");
                }
                Err(e) => {
                    eprintln!("Configuration validation failed: {}", e);
                    return Err(e.into());
                }
            }
        }
        Err(ConfigError::ParseWithContext { source }) => {
            eprintln!("TOML parsing error with context:\n{}", source);
            return Err("Config parse error".into());
        }
        Err(e) => {
            eprintln!("Configuration error: {}", e);
            return Err(e.into());
        }
    }
    
    Ok(())
}

```

--------------------------------

### tuigreet Background Animation Options

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/13-quick-reference.md

Enable and customize background animations like DOOM fire or Matrix rain. Adjust frame rate, dimensions, and colors for DOOM fire.

```bash
tuigreet --background doom       # DOOM fire effect
```

```bash
tuigreet --background matrix     # Matrix rain effect
```

```bash
tuigreet --background none       # Disable animation
```

```bash
tuigreet --background-fps 30     # Frame rate
```

```bash
tuigreet --doom-height 6         # Flame height (1-9)
```

```bash
tuigreet --doom-spread 2         # Flame width (0-4)
```

```bash
tuigreet --doom-colors "#9F2707,#C78F17,#FFFFFF"
```

--------------------------------

### NVIDIA with Sway Session Wrapper

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/10-power-and-sessions.md

Use a session wrapper to set GPU environment variables, such as for NVIDIA, before launching a specific session like Sway. This ensures the correct graphics drivers are used.

```toml
[session]
session_wrapper = "bash -c 'export __GLX_VENDOR_LIBRARY_NAME=nvidia; exec sway'"
```

--------------------------------

### Wayland (Sway) Session Configuration

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/13-quick-reference.md

Configure TuiGreet to work with Sway on Wayland. Ensure Wayland sessions are in the specified directory.

```toml
[session]
command = "sway"
sessions_dirs = ["/usr/share/wayland-sessions"]

[display]
show_time = true
battery = true
```

--------------------------------

### Create and set permissions for Tuigreet cache directory

Source: https://github.com/notashelf/tuigreet/blob/master/README.md

Commands to create the cache directory for `--remember*` features and set ownership and permissions. This is necessary if the cache is missing or owned by the wrong user.

```bash
# If cache is missing or owned by the wrong user, you may run the following
# commands to create it, or to fix the permissions.
$ mkdir /var/cache/tuigreet
$ chown greeter:greeter /var/cache/tuigreet
$ chmod 0755 /var/cache/tuigreet
```

--------------------------------

### IPC New Method

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/08-ipc-and-greetd.md

Creates a new `Ipc` instance. The connection to greetd is established lazily when first needed.

```rust
pub fn new() -> Self
```

--------------------------------

### tuigreet Main Binary Exported Types and Functions

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/12-module-overview.md

Defines core types for the greeter application, including `Greeter`, event enums (`Event`, `PowerCommand`, `PowerPostAction`), and asynchronous functions for handling greeter initialization, configuration access, keyboard input, UI drawing, and power commands.

```rust
pub struct Greeter { ... }
pub enum Event { Render, Key(KeyEvent), Exit(AuthStatus), PowerCommand(PowerCommand), Refresh, SetFrameRate(u32) }
pub enum PowerCommand { Shutdown, Reboot, Suspend, Hibernate }
pub enum PowerPostAction { ReturnToGreeter, ClearScreen }

impl Greeter {
    pub async fn new(events: Sender<Event>) -> Self
    pub fn config(&self) -> &getopts::Matches
}

pub async fn handle(greeter: Arc<RwLock<Greeter>>, key: KeyEvent, ipc: Ipc) -> Result<(), Box<dyn Error>>  // keyboard
pub async fn draw<B: Backend>(greeter: Arc<RwLock<Greeter>>, terminal: &mut Terminal<B>) -> Result<(), Box<dyn Error>>  // ui
pub async fn run(greeter: &Arc<RwLock<Greeter>>, command: PowerCommand) -> PowerPostAction  // power
```

--------------------------------

### Configure Greetd Socket Path

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/08-ipc-and-greetd.md

Sets the GREETD_SOCK environment variable to specify the greetd socket path, overriding the default. This is useful for custom configurations or when greetd is not running at the default location.

```bash
export GREETD_SOCK=/run/greetd.sock
tuigreet
```

--------------------------------

### Username Mode Keybindings

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/09-keyboard-and-events.md

Keybindings available when the greeter is in Username mode.

```APIDOC
## Username Mode Keybindings

### Description
Keybindings available when the greeter is in Username mode.

### Keybindings
| Key | Action |
|-----|--------|
| Printable chars | Add to buffer |
| Backspace | Delete last character |
| Tab | (no-op) |
| Enter | Send `CreateSession` to greetd |
| F1 | Show help menu |
| F2 (command) | Switch to Command edit mode |
| F3 (sessions) | Switch to Sessions menu |
| F4 (background) | Switch to Background menu |
| F12 (power) | Switch to Power menu |
| ESC | Cancel |
```

--------------------------------

### Apply Theme to Ratatui Span

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/03-theme-system.md

Demonstrates how to parse a theme string, obtain a ratatui Style object for text, and apply it to a ratatui Span.

```rust
use tuigreet_theme::{Theme, Themed};
use ratatui::text::Span;
use ratatui::style::Style;

let theme = Theme::parse("text=white");
let style = theme.of(&[Themed::Text]);

let span = Span::styled("Hello, world!", style);
```

--------------------------------

### tuigreet Display Options

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/13-quick-reference.md

Control how time, greetings, system information, and battery status are displayed. Adjust container width as needed.

```bash
tuigreet --time              # Show current time
```

```bash
tuigreet --time-format "%H:%M"  # Custom time format
```

```bash
tuigreet --greeting "Welcome"   # Custom greeting message
```

```bash
tuigreet --issue             # Show /etc/issue
```

```bash
tuigreet --battery           # Show battery percentage
```

```bash
tuigreet --width 100         # Container width (default: 80)
```

--------------------------------

### handle Function

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/09-keyboard-and-events.md

Central keyboard event dispatcher that routes input based on the current greeter mode. It processes keyboard events, updates the greeter state, and sends IPC requests as needed.

```APIDOC
## handle Function

### Description
Central keyboard event dispatcher that routes input based on current greeter mode.

### Signature
```rust
pub async fn handle(
    greeter: Arc<RwLock<Greeter>>,
    key: KeyEvent,
    ipc: Ipc,
) -> Result<(), Box<dyn Error>>
```

### Parameters
#### Path Parameters
- **greeter** (Arc<RwLock<Greeter>>) - Required - Shared greeter state
- **key** (KeyEvent) - Required - Keyboard event (key code, modifiers)
- **ipc** (Ipc) - Required - IPC connection to greetd

### Returns
- **Result<(), Box<dyn Error>>** - Error if operation fails

### Behavior
1. Match on current `greeter.mode`
2. Dispatch to mode-specific handler
3. Update greeter state (mode, buffer, cursor position)
4. Send IPC requests if needed
5. Return control to event loop
```

--------------------------------

### TuiGreet Module Dependencies

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/00-index.md

Lists the main module and its direct dependencies, including configuration, system interaction, theming, core types, internationalization, IPC, TUI rendering, and the async runtime.

```text
tuigreet (main)
├── tuigreet-config (configuration)
├── tuigreet-system (DRM/terminal)
├── tuigreet-theme (theming)
├── tuigreet-types (core types)
├── tuigreet-locales (i18n)
├── greetd_ipc (IPC protocol)
├── ratatui (TUI)
└── tokio (async runtime)
```

--------------------------------

### Build Individual Crate

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/12-module-overview.md

Command to build a specific crate, such as `tuigreet-config`, in release mode.

```bash
cargo build --release -p tuigreet-config
```

--------------------------------

### Full TOML Configuration Template

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/13-quick-reference.md

This is a comprehensive TOML configuration template for tuigreet. It includes settings for general options, display, layout, widgets, user menu, secrets, sessions, power management, keybindings, themes, backgrounds, outputs, and terminal settings.

```toml
[general]
debug = false
log_file = "/tmp/tuigreet.log"

[display]
show_time = true
time_format = "%H:%M:%S"
greeting = "Welcome!"
show_title = true
issue = false
battery = false
align_greeting = "center"

[layout]
width = 80
window_padding = 2
container_padding = 1
prompt_padding = 1

[layout.widgets]
time_position = "top"
status_position = "bottom"

[layout.widgets.status_bar]
show_reset = true
show_command = true
show_session = true
show_power = true
show_background = true

[remember]
username = true
session = false
user_session = true

[user_menu]
enabled = true
min_uid = 1000
max_uid = 60000

[secret]
mode = "characters"
characters = "*"

[session]
command = "sway"
sessions_dirs = ["/usr/share/wayland-sessions"]
xsessions_dirs = ["/usr/share/xsessions"]
session_wrapper = ""
xsession_wrapper = "startx /usr/bin/env"
environments = []

[power]
shutdown = ""
reboot = ""
suspend = ""
hibernate = ""
use_setsid = true

[keybindings]
command = 2
sessions = 3
power = 12
background = 4

[theme]
border = "white"
text = "green"
time = "blue"
container = "black"
title = "cyan"
greet = "yellow"
prompt = "magenta"
input = "white"
action = "bright-blue"
button = "bright-red"

[background]
kind = "doom"
fps = 30

[background.doom]
height = 6
spread = 2
top_color = "#9F2707"
middle_color = "#C78F17"
bottom_color = "#FFFFFF"

[background.matrix]
head_color = "#CCFFCC"
bright_color = "#33FF66"
dim_color = "#006622"
min_length = 6
max_length = 18
min_speed = 0.30
max_speed = 1.10
mutate_chance = 0.02

[[outputs]]
connector = "DP-1"
primary = true
enabled = true

[[outputs]]
connector = "HDMI-A-1"
enabled = false

[terminal]
cols = 120
rows = 40

```

--------------------------------

### Set GREETD_SOCK Environment Variable

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/13-quick-reference.md

Ensure the GREETD_SOCK environment variable is set to the correct path for greetd to function properly.

```bash
export GREETD_SOCK=/run/greetd.sock
```

--------------------------------

### Apply Custom Theme to Tuigreet

Source: https://github.com/notashelf/tuigreet/blob/master/README.md

Use the `--theme` argument to control UI colors. Enclose the theme specification in single-quotes to prevent shell interpretation of semicolons. The format is 'component=color;component=color'.

```sh
tuigreet --theme 'border=magenta;text=cyan;prompt=green;time=red;action=blue;button=yellow;container=black;input=red'
```

--------------------------------

### UI Rendering Event Flow

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/11-ui-rendering.md

Illustrates the sequence of events from receiving a Render event to displaying the UI on screen.

```text
Event::Render
    ↓
ui::draw()
    ↓
Redraw Terminal
    ↓
Show on screen
    ↓
Wait for next tick (2/30 FPS)
```

--------------------------------

### Run Full Test Suite with NSS Wrapper

Source: https://github.com/notashelf/tuigreet/blob/master/README.md

To run the entire test suite, including tests that mock NSS responses using libnss_wrapper, set the NSS_WRAPPER_PASSWD and NSS_WRAPPER_GROUP environment variables. Then, preload libnss_wrapper.so and execute cargo test with all features enabled.

```bash
# After installing `libnss_wrapper` on your system (or compiling it to get the`.so`)
# you can run those specific tests as such:
$ export NSS_WRAPPER_PASSWD=contrib/fixtures/passwd
$ export NSS_WRAPPER_GROUP=contrib/fixtures/group
$ LD_PRELOAD=/path/to/libnss_wrapper.so cargo test --features nsswrapper nsswrapper_ # to run those tests specifically
$ LD_PRELOAD=/path/to/libnss_wrapper.so cargo test --all-features # to run the whole test suite
```

--------------------------------

### Main Function Signature

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/07-main-entry-point.md

The entry point for the Tokio application. It sets up the TUI backend, event system, and Greeter instance before entering the main event loop.

```rust
#[tokio::main]
async fn main()
```

--------------------------------

### Greeter Default Implementation

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/06-greeter-struct.md

Provides a default implementation for the Greeter struct, initializing all fields to sensible defaults.

```rust
impl Default for Greeter {
    fn default() -> Self { ... }
}
```

--------------------------------

### Power Command Execution Function

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/10-power-and-sessions.md

Asynchronously executes a specified power command. It takes the greeter state and the power command as input and returns a `PowerPostAction` to indicate the next step.

```rust
async fn run(
    greeter: &Arc<RwLock<Greeter>>,
    command: PowerCommand,
) -> PowerPostAction
```

--------------------------------

### Parse and Apply Theme

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/00-index.md

Parses a theme string and retrieves specific styled elements like text and border.

```rust
use tuigreet_theme::{Theme, Themed};

let theme = Theme::parse("text=white;border=cyan");
let style = theme.of(&[Themed::Text, Themed::Border]);
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/00-index.md

Enables debug logging for Tuigreet and tails the log file in real-time.

```bash
tuigreet --debug --log-file /tmp/tuigreet.log
tail -f /tmp/tuigreet.log
```

--------------------------------

### Configure DRM Output

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/13-quick-reference.md

Define output configurations, including the connector and primary display, for DRM.

```toml
[[outputs]]
connector = "DP-1"
primary = true
```

--------------------------------

### Command Edit Mode Keybindings

Source: https://github.com/notashelf/tuigreet/blob/master/_autodocs/09-keyboard-and-events.md

Keybindings available when the greeter is in Command Edit mode.

```APIDOC
## Command Edit Mode Keybindings

### Description
Keybindings available when the greeter is in Command Edit mode.

### Keybindings
| Key | Action |
|-----|--------|
| Printable chars | Add to buffer |
| Backspace | Delete last character |
| Home | Move to start of line |
| End | Move to end of line |
| Left/Right | Move cursor |
| Enter | Save command, return to username mode |
| ESC | Discard changes, return to username mode |
```