latchd/docs/ui.md

User interface

The screen is designed for a virtual terminal. It keeps the session list beside the account and password fields, and adapts down to 60 columns by 16 rows.

Preview mode screenshot of the login layout.

Fields and status

• session list — choose an X11, Wayland, administrator-script, or TTY entry
• username — type an account name or select one discovered through NSS
• password — enter the password; the screen clears it after an attempt
• status line — shows focus prompts, account state, faillock counts, notices, and authentication progress
• footer — shows the keys that apply to the current screen state

When the selected account needs a new password, the password field changes to the new-password prompt. The old password stays in the pending authentication request until the password-change call finishes, then both values are cleared.

Keys

Key	Action
Tab / Shift-Tab	Move between session, username, and password
Up / Down	Move focus, or move through the filtered list
Left / Right	Change the session when the session list has focus
/	Start a session or account filter
Ctrl-R	Refresh accounts and sessions in the background
Ctrl-N / Ctrl-P	Select the next or previous account
Ctrl-B	Toggle the wallpaper and ambient animation
Ctrl-M	Toggle reduced motion
Enter	Start login or submit a new password
Esc	Clear the password, close a popup, or cancel power confirmation
?	Open the key reference
Ctrl-C	Restore the terminal and exit
F1–F12	Confirm the matching configured power action

Lowercase filters ignore case. A filter with an uppercase character uses case-sensitive matching. Press Esc while filtering to leave the filter field.

Visual settings

The [visual] section controls the background:

[visual]
background_enabled = true
animations = true
notifications = true
reduced_motion = false
max_wallpaper_bytes = 8388608
# wallpaper_path = "/etc/latchd/wallpaper.png"

wallpaper_path accepts a root-owned PNG or JPEG file. The loader checks the file size and source dimensions, then scales the image before it draws it in the terminal. animations = false stops frame updates at startup, while reduced_motion = true does the same and can also be changed with Ctrl-M.

Set LATCHD_ASCII=1 for terminals without reliable Unicode cells, NO_COLOR=1 for plain output, and LATCHD_HIGH_CONTRAST=1 for a stronger focus style.

Help panel

Press ? to open the key reference:

Press Esc or ? again to close it. The help panel does not change the selected account or session.

Capture the screen

Build the Docker test image, then start a PTY with a fixed size:

docker build -f Dockerfile.test -t latchd-test:local .
tmux new-session -d -x 120 -y 36 \
  'docker run --rm -it latchd-test:local /workspace/target/release/latchd --preview --no-log'

The capture shows the preview binary and terminal renderer, preview mode is simply for testing and doesn't perform any real login.