EMPTTY(1)

📦
version 0.16.1 · 3 versions
, in alpine 3.24, arch rolling

💖 EMPTTY(1) — the emptty era 💖

✨ NAME ✨

emptty — dead simple CLI Display Manager on TTY. That's literally the whole name, bestie. 💅

🦋 SYNOPSIS 🦋

emptty [-v] [--version] [-d] [--daemon] [-c PATH] [--config PATH] [-i]
[--ignore-config] [-t TTY] [--tty TTY] [-u defaultUser] [--default-user
defaultUser] [-a [session]] [--autologin [session]]

💅 DESCRIPTION 💅

Okay so emptty is a simple CLI Display Manager, and it's giving main character energy on your TTY. It lets you select a DE/WM after login, use predefined config, or do autologin if the selected user is part of the nopasswdlogin group. Periodt. 🌸

🌟 OPTIONS 🌟

  • -v, --version — displays the version of the program. Iconic little flex. 💖
  • -d, --daemon — starts emptty as a daemon, which does not require agetty. 🦋
  • -c, --config PATH — loads configuration from the specified path. 🎀
  • -C, --print-config — only prints the loaded configuration and exits. No extra drama. ✨
  • -i, --ignore-config — skips loading configuration from file and loads only argument configuration. 🫶
  • -t, --tty TTY — overrides the loaded configuration by setting the defined TTY. May be specified as a number (e.g. "7") or a TTY name (e.g. "tty7"). 💜
  • -u, --default-user defaultUser — overrides the loaded configuration by setting the defined defaultUser. 🌈
  • -a, --autologin [session] — overrides the loaded configuration by enabling autologin. If session is defined, it overrides the autologin session. 🔥

🎀 CONFIG 🎀

The config file lives at /etc/emptty/conf, and these are the keys that matter:

  • TTY_NUMBER — TTY where emptty will start. 🖥️
  • SWITCH_TTY — enables switching to the defined TTY number. Default is true. 🔁
  • PRINT_ISSUE — enables printing of /etc/issue in daemon mode. 📜
  • PRINT_MOTD — enables printing of default motd, static motd or dynamic motd. 💌
  • DEFAULT_ENV — defines the default environment used for starting undefined sessions (e.g. from emptty file). Possible values are "xorg" and "wayland". The default of the default is xorg. 🌱
  • DEFAULT_USER — preselected user. If AUTOLOGIN is enabled, this user is logged in. 👤
  • DEFAULT_SESSION — preselected desktop session, if the user does not use the emptty file. Has lower priority than AUTOLOGIN_SESSION. 🎯
  • DEFAULT_SESSION_ENV — optional environment of the preselected desktop session, if the user does not use the emptty file. Possible values are "xorg" and "wayland". 🧚
  • AUTOLOGIN — enables autologin if DEFAULT_USER is defined. Possible values are "true" or "false". Default value is false.
NOTE: to enable autologin, DEFAULT_USER must be in group nopasswdlogin; otherwise the user will NOT be authorized. 💀
  • AUTOLOGIN_SESSION — the default session used if autologin is enabled. If the session is not found in the list of session, it proceeds to manual selection. 🌀
  • AUTOLOGIN_SESSION_ENV — optional environment of the autologin desktop session. Possible values are "xorg" and "wayland". 🌸
  • AUTOLOGIN_MAX_RETRY — if the session does not start correctly in the specified period, the number of retries in a short period is kept so it can eventually stop the infinite loop of restarts. -1 is for infinite retries, 0 is for no retry. Default value is 2. 😮‍💨
  • AUTOLOGIN_RETRY_PERIOD — time period in seconds that is used for checking session login retries. Default value is 2. ⏱️
  • LANG — defines locale for all users. Default value is "en_US.UTF-8". 🌍
  • DBUS_LAUNCH — starts dbus-launch before the desktop command. After the end of the session, dbus-daemon is interrupted. Default value is true. If the user config is handled as a script (does not contain Exec option), this config is overridden to false. 🚌
  • ALWAYS_DBUS_LAUNCH — starts dbus-launch before the desktop command in any case; the DBUS_LAUNCH value is ignored. It also starts even if XINITRC_LAUNCH is set to true. After the end of the session, dbus-daemon is interrupted. Default value is false. 💫
  • XINITRC_LAUNCH — starts an Xorg desktop by calling the ~/.xinitrc script with session exec as an argument. If it is true, the file exists, and the selected WM/DE is an Xorg session, it overrides DBUS_LAUNCH. If the user config is handled as a script (does not contain Exec option), this config is overridden to false. 🪄
  • VERTICAL_SELECTION — prints available WM/DE each on a new line instead of printing on a single line. 📋
  • INDENT_SELECTION — horizontal offset for vertical selection, useful for centering the menu on screen. 🎯
  • LOGGING — defines how logging is handled. Possible values are "rotate", "appending" or "disabled". Default value is "rotate". 🪵
  • LOGGING_FILE — overrides the path of the log file. Default value is /var/log/emptty/[TTY_NUMBER].log.
NOTE: it expects the existence of directories to the defined logging file. 📁
  • XORG_ARGS — arguments passed to the Xorg server. 🖥️
  • DYNAMIC_MOTD — allows using a dynamic motd script to generate a custom MOTD. Possible values are "true" or "false". Default value is false.
NOTE: be sure that the dynamic motd has correct content and permissions (e.g. 744). The script is started as default user; in daemon mode it means root. 🫶
  • DYNAMIC_MOTD_PATH — allows overriding the default path to the dynamic motd. Default value is "/etc/emptty/motd-gen.sh". 🌟
  • MOTD_PATH — allows overriding the default path to the static motd. Default value is "/etc/emptty/motd". 💌
  • FG_COLOR — foreground color, available only in daemon mode. The list of colors is listed below. 🎨
  • BG_COLOR — background color, available only in daemon mode. The list of colors is listed below. 🖌️
  • DISPLAY_START_SCRIPT — script started before Display (Xorg/Wayland) starts.
NOTE: the script is started as default user; in daemon mode it means root. 🧨
  • DISPLAY_STOP_SCRIPT — script started after Display (Xorg/Wayland) stops.
NOTE: the script is started as default user; in daemon mode it means root. 🧨
  • ENABLE_NUMLOCK — enables numlock in daemon mode. Possible values are "true" or "false". Default value is false. 🔢
  • SESSION_ERROR_LOGGING — defines how logging of session errors is handled. Possible values are "rotate", "appending" or "disabled". Default value is "disabled". 🚨
  • SESSION_ERROR_LOGGING_FILE — overrides the path of the session errors log file. Default value is /var/log/emptty/session-errors.[TTY_NUMBER].log.
NOTE: it expects the existence of directories to the defined logging file. 📁
  • NO_XDG_FALLBACK — disallows setting fallback values for all XDG environmental variables and leaves it on Login Controls. Possible values are "true" or "false". Default value is false.
NOTE: be aware that setting it to "true" could lead to unexpected behaviour. 😭
  • DEFAULT_XAUTHORITY — if set true, it will not use the .emptty-xauth file, but the standard ~/.Xauthority file. This allows handling xauth issues. Possible values are "true" or "false". Default value is false. 🔐
  • ROOTLESS_XORG — if set true, Xorg will be started as rootless, if the system allows and emptty is running in daemon mode. Possible values are "true" or "false". Default value is false. 🕊️
  • IDENTIFY_ENVS — if set true, environmental groups are printed to differ Xorg/Wayland/Custom/UserCustom desktops. Possible values are "true" or "false". Default value is false. 🏷️
  • HIDE_ENTER_LOGIN — if set true, "hostname login:" is not displayed. Possible values are "true" or "false". Default value is false. 🙈
  • HIDE_ENTER_PASSWORD — if set true, "Password:" is not displayed. Possible values are "true" or "false". Default value is false. 🙈
  • XORG_SESSIONS_PATH — path to the directory where Xorg sessions' desktop files are stored. Default value is "/usr/share/xsessions/". 📂
  • WAYLAND_SESSIONS_PATH — path to the directory where Wayland sessions' desktop files are stored. Default value is "/usr/share/wayland-sessions/". 📂
  • SELECT_LAST_USER — enables funtionality of saving the last successfully logged in user for next login. Possible values are "false", "per-tty" or "global". Default value is false. 🫶
  • AUTO_SELECTION — if set to "true" and only one desktop is available, it automatically selects that desktop. Possible values are "true" or "false". Default value is false. 🎯
  • ALLOW_COMMANDS — if set to "true" and no default user is selected, it allows entering commands into the login input. Possible values are "true" or "false". Default value is true. ⌨️
  • CMD_POWEROFF — command to be used to perform poweroff. Default value is "poweroff". 🔌
  • CMD_REBOOT — command to be used to perform reboot. Default value is "reboot". 🔄
  • CMD_SUSPEND — command to be used to perform suspend. Default value is blank, but it tries to use "systemctl suspend", "loginctl suspend" or "zzz". 😴
  • WAIT_EXIT_TIMEOUT — timeout in seconds before emptty automatically exits. If the value is 0 or lower, there is no timeout. Default value is -1. ⏳

🔥 COMMANDS 🔥

If commands are allowed and no default user is defined, you can use commands in the login input. All of these commands need to start with a colon ":". Escape characters are ignored to prevent issues with muscle memory from VI. 😅

  • :help, :? — prints available commands. 🆘
  • :poweroff, :shutdown — processess the poweroff command. 🔌
  • :reboot — processes the reboot command. 🔄
  • :suspend, :zzz — processes the suspend command. 😴

🌈 DYNAMIC MOTD 🌈

Optional file stored by default as /etc/emptty/motd-gen.sh. Could be overridden. 🧚

If DYNAMIC_MOTD is set to true, this file exists, and is executable for its owner, the result is printed as your own MOTD. Be very careful with this script! 🫶

⭐ CUSTOM MOTD ⭐

Optional file stored by default as /etc/emptty/motd. Could be overridden. 🎀

It's a custom file that prints your own MOTD. Reading this file supports colors (e.g. \x1b[31m or \033[32m). 🌈

💖 USER CONFIG 💖

Okay bestie, this is your personal little config corner. It’s optional, and it lives at ${HOME}/.config/emptty or ${HOME}/.emptty.

Heads up: the file stored as ${HOME}/.config/emptty has higher priority when loading. So if both exist, that’s the main character.

  • Name — optional name to be used as the Session Name. Cute label energy.
  • Exec — defines the command to start the Desktop Environment/Window Manager. You do not need to define this if your user config is presented as a shell script (with a shebang at the start and execution permissions). Slay, script bestie.
  • Environment — selects which environment should be defined for the following command. Possible values are "xorg" and "wayland"; "xorg" is the default.
  • Lang — defines the locale for the logged user. It has higher priority than LANG from the global configuration. Respect the hierarchy 💅
  • Selection — requires selection of desktop, and basically turns the emptty file into .xinitrc for Xorg and Wayland. In this case Exec is skipped. Possible values are "false" for never using selection, "true" for always showing selection, or "auto" for showing selection or first option autoselect if there is no other desktop. Default value is false.
  • LoginShell — defines a custom shell to be used to start the session. This lets you start the session with a non-interactive shell, e.g. "/bin/bash --login". Iconic.
  • DesktopNames — value passed into XDG_CURRENT_DESKTOP. That’s the whole job 🫶

🦋 USER EXIT SCRIPT 🦋

There’s an optional script file stored as ${HOME}/.config/emptty-exit. It’s handled as a shell script and is started when the session is going to end. It is started even if emptty is being terminated. The default timeout to finish the script is 3 seconds, but it’s configurable from the script itself.

  • Timeout — optional custom timeout for the script to finish its run. The number represents seconds. Default is 3.

No cap, it will run on the way out. So set your timeout if you need more time to say bye 😭

🌈 CUSTOM SESSIONS 🌈

Optional folders for custom sessions, which could be available system-wide — in the case of /etc/emptty/custom-sessions/ — or user-specific — in the case of ${HOME}/.config/emptty-custom-sessions/ — but do not have a .desktop file stored on standard paths for Xorg or Wayland sessions. The expected suffix of each file is ".desktop".

  • Name — defines the name of the Desktop Environment/Window Manager.
  • Exec — defines the command to start the Desktop Environment/Window Manager. It could contain multiple arguments, same as in *.desktop files.
  • Environment — selects which environment should be defined for the following command. Possible values are "xorg" and "wayland"; "xorg" is the default.
  • DesktopNames — value passed into XDG_CURRENT_DESKTOP.
  • NoDisplay/Hidden — Boolean value that controls visibility of the desktop session. Sneaky little session, iykyk 👀

🎀 LAST SESSION 🎀

The last user selection of session is stored into ~/.cache/emptty/last-session.

It remembers. It’s giving main character continuity ✨

🔥 LOGGING 🔥

As it is mentioned in configuration, there are three options to handle logging of emptty. The logs contain not just logs from emptty, but also from Xorg (if used) and the user’s WM/DE. The described log location could differ according to LOGGING_FILE, which is stored in /etc/emptty/conf.

🌙 default

This option provides a simple solution, where the current instance of emptty logs into /var/log/emptty/[TTY_NUMBER].log and the previous version is stored as /var/log/emptty/[TTY_NUMBER].log.old.

NOTE: The current instance always moves the previous log into the old file. So if emptty crashes and is started again, the previous log is in /var/log/emptty/[TTY_NUMBER].log.old.

🌸 appending

This option provides functionality that logs everything into /var/log/emptty/[TTY_NUMBER].log and does not handle log rotation by itself. It leaves the option for the user to handle it themselves (e.g. with logrotate).

NOTE: Appending without rotation could cause a large log file, so be sure that the log file is rotated. Bestie, please rotate it. Don’t let it become a whole monster 😭

💀 disabled

This option points all logs into /dev/null, so no log is available.

NOTE: If any issue starts to appear and you want to report it, ensure you do not use this option. Fr fr, no logs means no clues.

💜 COLORS 💜

Please, be aware that LIGHT_ colors could be unavailable as background color. That’s the warning, bestie.

  • BLACK, RED, GREEN, YELLOW, BLUE, PURPLE, CYAN, WHITE
  • LIGHT_BLACK, LIGHT_RED, LIGHT_GREEN, LIGHT_YELLOW, LIGHT_BLUE, LIGHT_PURPLE, LIGHT_CYAN, LIGHT_WHITE

And that’s the whole vibe, bestie: this iconic page is from emptty 0.16.1, dated March 2026, and yes, it’s EMPTTY(1) 💅✨ go log in slayfully 🎀

📦 where this page comes from