footclient(1)

📦
version 1.28.0 · 16 versions
, in arch rolling

🌸 footclient(1) — the General Commands Manual page, but make it make sense 💅

okay bestie, so you know how foot(1) can run as a server? yeah. this is the little buddy that talks to it. it's footclient, and it's literally the icon that opens new terminals inside a foot server. let's get into it 🫶

✨ NAME ✨

footclient — start new terminals in a foot server. that's the whole job. main character energy, minimal responsibilities. 🎀

🦋 SYNOPSIS 🦋

footclient [OPTIONS]
footclient [OPTIONS] <command> [COMMAND OPTIONS]

so here's the vibe: all trailing (non-option) arguments get treated as a command, plus its arguments, and that's what gets executed — instead of the default shell. no cap, everything after the options is the command. ✨

💖 DESCRIPTION 💖

footclient is used together with foot(1) in --server mode. they're a duo, iykyk.

run it with no arguments and it opens a brand new terminal window (hosted in the foot server, obviously) running your default shell. the exit code you get back will be that of the terminal. meaning: footclient does not exit until the terminal has terminated. it's committed. it's in it for the long haul. 😭

🔥 OPTIONS 🔥

  • -t, --term=TERM — the value that gets set into the environment variable TERM (peep TERMINFO and ENVIRONMENT below). default: foot.
  • -T, --title=TITLE — initial window title. default: foot.
  • -a, --app-id=ID — the value to set the app-id property on the Wayland window to. default: foot (normal mode), or footclient (server mode). she contains multitudes.
  • --class=ID — alias for --app-id. same thing, different font. 💅
  • toplevel-tag=TAG — the value to set the toplevel-tag property on the Wayland window to. the compositor can use this value for session management, window rules, etc. default: not set.
  • -w, --window-size-pixels=WIDTHxHEIGHT — set the initial window width and height, in pixels. default: 700x500.
  • -W, --window-size-chars=WIDTHxHEIGHT — set the initial window width and height, in characters. default: not set.
  • -m, --maximized — start in maximized mode. if both --maximized and --fullscreen are specified, the last one takes precedence. order matters, bestie. 🫶
  • -F, --fullscreen — start in fullscreen mode. if both --maximized and --fullscreen are specified, the last one takes precedence. yes, same rule. they're not fighting, they're just taking turns.
  • -L, --login-shell — start a login shell, by prepending a '-' to argv[0]. classic move.
  • -D, --working-directory=DIR — initial working directory for the client application. default: the CWD of footclient.
  • -s, --server-socket=PATH — connect to PATH instead of $XDG_RUNTIME_DIR/foot-$WAYLAND_DISPLAY.sock.
  • -H, --hold — remain open after the child process exits. clingy in a cute way 🥺
  • -N, --no-wait — detach the client process from the running terminal, exiting immediately. bye bestie 👋
  • -o, --override=[SECTION.]KEY=VALUE — override an option set in the configuration file. if SECTION is not given, it defaults to main.
  • -E, --client-environment — the child process in the new terminal instance will use footclient's environment, instead of the server's. ⚠️ but heads up: environment variables listed in the Variables set in the child process section will be overwritten by the foot server anyway. so for example, the new terminal will use TERM from the configuration, not footclient's environment. sneaky but real.
  • -d, --log-level={info,warning,error,none} — log level, used both for log output on stderr as well as syslog. default: warning.
  • -l, --log-colorize=[{never,always,auto}] — enables or disables colorization of log output on stderr. aesthetic logging, lowkey essential 🌈
  • -v, --version — show the version number and quit.
  • -e — ignored; for compatibility with xterm -e. see foot(1) for more details. it's just there so old scripts don't cry.

💀 EXIT STATUS 💀

  • footclient will exit with code 220 if there's a failure in footclient itself (for example, the server socket does not exist). that's a you problem, not a server problem.
  • if -N, --no-wait is used, footclient exits with code 0 as soon as the foot server has been instructed to open a new window. mission accomplished, dipping immediately.
  • if not, footclient may also exit with code 230. this indicates a failure in the foot server. not her fault, fr fr.
  • in all other cases the exit code is that of the client application (i.e. the shell).

🧚 TERMINFO 🧚

client applications use the terminfo identifier specified by the environment variable TERM (set by foot) to determine terminal capabilities.

foot has two terminfo definitions: foot and foot-direct, with foot being the default.

the difference between the two is in the number of colors they describe: foot describes 256 colors and foot-direct describes 16.7 million colors (24-bit truecolor). slay 💅

⭐ note that using the foot terminfo does not limit the number of usable colors to 256; applications can still use 24-bit RGB colors. in fact, most applications work best with foot (including 24-bit colors)). using *-direct terminfo entries has been known to crash some ncurses applications even. 💀 so like… be careful.

there are however applications that need a *-direct terminfo entry for 24-bit support. Emacs is one such example. (emacs stays emacs-ing 🙈)

while using either foot or foot-direct is strongly recommended, it is possible to use e.g. xterm-256color as well. this can be useful when remoting to a system where foot's terminfo entries cannot easily be installed.

🎀 note that terminfo entries can be installed in the user's home directory. i.e. if you do not have root access, or if there is no distro package for foot's terminfo entries, you can install foot's terminfo entries manually, by copying foot and foot-direct to ~/.terminfo/f/. no sudo needed, we love to see it.

🌈 ENVIRONMENT 🌈

🦋 Variables used by footclient

  • XDG_RUNTIME_DIR — used to construct the default PATH for the --server-socket option, when no explicit argument is given (see above).
  • WAYLAND_DISPLAY — used to construct the default PATH for the --server-socket option, when no explicit argument is given (see above). yep, same line. they're a team. 🫶

if the socket at the default PATH does not exist, footclient will fallback to the less specific path, with the following priority:

  1. $XDG_RUNTIME_DIR/foot-$WAYLAND_DISPLAY.sock
  2. $XDG_RUNTIME_DIR/foot.sock
  3. /tmp/foot.sock

💜 Variables set in the child process

  • TERM — terminfo/termcap identifier. this is used by client applications to determine which capabilities a terminal supports. the value is set according to either the --term command-line option or the term config option in foot.ini(5).
  • COLORTERM — this variable is set to truecolor, to indicate to client applications that 24-bit RGB colors are supported. 🎨
  • PWD — current working directory (at the time of launching foot).
  • SHELL — set to the launched shell, if the shell is valid (it is listed in /etc/shells).

in addition to the variables listed above, custom environment variables may be defined in foot.ini(5).

🙈 Variables unset in the child process

  • TERM_PROGRAM, TERM_PROGRAM_VERSION — these environment variables are set by certain other terminal emulators. we unset them, to prevent applications from misdetecting foot. not on our watch. 💅

in addition to the variables listed above, custom environment variables to unset may be defined in foot.ini(5).

⭐ Signals ⭐

the following signals have special meaning in footclient:

  • SIGUSR1: switch to the dark color theme ([colors-dark]). 🖤
  • SIGUSR2: switch to the light color theme ([colors-light]). 🤍

when sending SIGUSR1/SIGUSR2 to a footclient instance, the theme is changed in that instance only. this is different from when you send SIGUSR1/SIGUSR2 to the server process, where all instances change the theme. big difference, don't mix it up bestie. 😭

note: for obvious reasons, this is not supported when footclient is started with --no-wait. obviously. she's already gone. 💀

🎀 SEE ALSO 🎀

foot(1) — go read that one too, it's the whole other half of the duo 🫶

and that's the page, bestie ✨ this was the footclient(1) page from the General Commands Manual, dated 2026-09-08, and it says footclient(1) in the corner because obviously it does 💅 periodt. 🌸

📦 where this page comes from