tuigreet

tuigreet

Stylish, modern and extensible greeter for greetd, built on top of the original tuigreet foundation with a focus on improved maintainability, a cleaner codebase, and a more polished user experience.

Features

tuigreet provides a terminal-based authentication interface with session management, user selection, and power controls. The upstream project includes session launching from desktop files, username/session persistence, NSS-backed user menus, themeable UI components, and multi-language support.

Usage

The default configuration of tuigreet is quite minimal, visually speaking. It only displays the authentication prompt and some minor information in the status bar. You may additionally print your system's /etc/issue at the top of the prompt with --issue, and the current date & time using --time. The time can also be customized with the --time-format flag. It is also possible to include a custom, one-line greeting message instead of /etc/issue using the --greeting flag.

Prompt Customization

The initial prompt container will be 80 columns wide. You might want to change this using the --width flag in the case you need more space, e.g., to account for larger PAM challenge messages. Please refer to usage information (--help) for more customization options. Various padding settings are available through the *-padding options.

Session Persistence

You can instruct tuigreet to remember the last username that successfully opened a session with the --remember option (that way, the username field will be pre-filled). Similarly, the command and session configuration can be retained between runs with the --remember-session option (when using this, the --cmd value is overridden by manual selections). You can also remember the selected session per user with the --remember-user-session flag. In this case, the selected session will only be saved on successful authentication.

You may change the command that will be executed after opening a session by hitting F2 and amending the command. Alternatively, you can list the system-declared sessions (or custom ones) by hitting F3. Power options are available through F12.

Background animations

tuigreet can paint an animated backdrop behind the login form. Animations are off by default and selected by name with --background <name>, or by setting kind in the [background] section of your config file. The login form is drawn on top of the animation and clears the cells it occupies, so the prompt remains legible regardless of what the backdrop is doing.

Frame rate is configurable through --background-fps, and defaults to 30 FPS while an animation is active (the UI otherwise ticks at the usual 2 FPS). Setting --background none (or omitting the flag) disables the feature entirely, in which case there is no per-frame cost.

The following animation is available out of the box:

• doom - The classic DOOM fire effect. Two parameters control the shape of the flames: --doom-height (decay control, 1–9, default 6) makes flames taller at higher values, and --doom-spread (horizontal jitter, 0–4, default 2) widens them. The three color bands are set together with --doom-colors TOP,MIDDLE,BOTTOM; each accepts #RRGGBB, 0xRRGGBB, or any named color.
• matrix - Falling green digital rain. Stream length is set with --matrix-length MIN,MAX (rows, default 6,18) and fall speed with --matrix-speed MIN,MAX (rows-per-frame, default 0.30,1.10); the three color bands are set together with --matrix-colors HEAD,BRIGHT,DIM.

You can also switch animations on the fly without restarting the greeter by hitting F4. This opens a small menu listing every available animation plus a None entry to disable the backdrop; selection rebuilds the active animation with that kind's default options. The hotkey is configurable through --kb-background or the background field of the [keybindings] section, the same way the existing F2/F3/F12 menus are configured.

Installing Tuigreet

There are various methods of installing Tuigreet, and you're recommended to pick the appropriate method for your distribution or preferred package manager. We provide pre-built binaries for tagged releases, which can be obtained from the releases tab. Additionally, the maintainers of this project maintain packages for the Arch Linux AUR and Nix via flakes. If none of those interest you, you may build from source. Should you wish to package this for your distribution, please do, and submit a pull request to update the readme with per-distribution instructions. We will be happy to review :)

From the AUR

On ArchLinux, two distributions are available from the AUR. greetd-tuigreet-fork-bin is the precompiled binary for the latest tagged release, and greetd-tuigreet-fork-git is available for the same tagged release, but you compile it yourself from the latest commit Those can be installed via your preferred AUR helper, e.g.:

# Install the built binary from the AUR. This uses tuigreet's own releases.
$ yay -S greetd-tuigreet-fork-bin

# Alternatively, use the -git version to build from source. This depends on
# the Rust toolchain.
$ yay -S greetd-tuigreet-fork-git

With Nix

Nix is the primary method of installing, and often times developing, tuigreet.

From Nixpkgs

Nixpkgs provides a pkgs.tuigreet that you can use to install tuigreet on your system, using the greetd module under services.greetd:

{
  services.greetd = {
    enable = true;
    settings = {
      default_session = {
        user = "greeter";
        command = getExe' pkgs.tuigreet "tuigreet"; # you may pass `--config` here
      };
    };
  };
}

Using Flakes

Alternatively, you may use Nix flakes to build the package from source using Nix. Use the package exposed by packages.<system> as, e.g., inputs.tuigreet.packages.${prev.hostPlatform.system}.tuigreet.

To get development versions of tuigreet it is trivial to use the Nixpkgs derivation with the updated source information, should you wish to run it. For example, you may create an overlay to override pkgs.tuigreet as follows:

…

Once applying the overlay as you see fit, you may use the greetd module as described above.

From source

Building Tuigreet from source requires an installation of Rust's stable toolchain. Currently 1.90 and above is required. You may use the Nix devshell provided by the repository, or install it using something like rustup.

# Clone the repository and navigate to it
$ git clone https://github.com/tuigreet/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
# You can also use cargo to build and install from Git:
# $ cargo install --git https://github.com/tuigreet/tuigreet --locked

[!NOTE] Cache directory must be created for --remember* features to work. The directory must be owned by the user running the greeter. This is handled automatically if using the NixOS module in Nixpkgs.

# 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

Pre-built binaries

Pre-built binaries of tuigreet for several architectures can be found in the releases section of this repository. You may download a binary for your architechture, and add it to your PATH to make it available on your system.

Configuration

Edit /etc/greetd/config.toml and set the command setting to use tuigreet:

[terminal]
vt = 1

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

Please refer to greetd's wiki for more information on setting up greetd.

TOML Configuration

tuigreet supports TOML configuration files in addition to command-line options. Configuration files are loaded from:

1. ~/.config/tuigreet/config.toml (user config)
2. /etc/tuigreet/config.toml (system config)
3. Custom path via --config <path>

Configuration priority: CLI args > environment variables > user config > system config > defaults

Configuration Example

…

Environment Variables

All configuration options can also be set via environment variables. The naming convention is TUIGREET_<SECTION>_<KEY> for nested options, or TUIGREET_<KEY> for top-level options:

…

Hot Reload

Configuration files are automatically monitored for changes and hot-reloaded when modified. This allows you to adjust settings without restarting the greeter.

Configuration Errors

tuigreet makes an effort to include detailed context with line numbers and source code snippets to help identify and fix configuration issues. For example:

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 `=`

Multi-monitor Support

On multi-monitor setups the Linux virtual console may span all connected displays, leaving the greeter rendered across a larger-than-intended area. tuigreet can resize the TTY to match the native resolution of a specific monitor by reading connector information from /sys/class/drm/ and applying the new dimensions via TIOCSWINSZ before the TUI starts.

To see which connectors are available on your system, run:

tuigreet --list-outputs

Then declare the target display in your config. Mark one output primary = true to use it for sizing; if none is marked primary the first enabled entry is used. Disable any outputs you do not want to affect sizing with enabled = false:

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

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

If you already know the exact character-cell dimensions you want (e.g. from a fixed font size), you can bypass the DRM detection entirely with an explicit override. Both cols and rows must be provided together:

[terminal]
cols = 237
rows = 52

[terminal] takes precedence over [[outputs]] when both are set.

Sessions

The available sessions are discovered by iterating over all paths present in the $XDG_DATA_DIRS environmental variable, then looking for .desktop files in xsessions/ and wayland-sessions/ subdirectories. If you want to search for sessions in custom directories, you can set the --sessions arguments with a colon-separated list of directories.

On most Linux distributions, .desktop files are stored in the /usr/share/xsessions and /usr/share/wayland-sessions directories respectively.

Desktop environments

greetd only accepts environment-less commands to be used to start a session. Therefore, if your desktop environment requires either arguments or environment variables, you will need to create a wrapper script and refer to it in an appropriate desktop file.

For example, to run X11 Gnome, you may need to start it through startx and configure your ~/.xinitrc (or an external xinitrc with a wrapper script):

exec gnome