foot(1)

📦
version 1.28.0 · 16 versions
, in arch rolling

foot(1) from the General Commands Manual — okay bestie, this is the Wayland terminal emulator page, and we're gonna get through every single flag together. 💅✨

🌸 NAME 🌸

foot — Wayland terminal emulator. Short, iconic, to the point. 🎀

✨ SYNOPSIS ✨

foot [OPTIONS]
foot [OPTIONS] <command> [COMMAND OPTIONS]

All trailing (non-option) arguments are treated as a command, and its arguments, to execute (instead of the default shell). fr fr, that's the whole synopsis vibe. 🦋

🎀 DESCRIPTION 🎀

foot is a Wayland terminal emulator. Running it without arguments will start a new terminal window with your default shell. Literally that simple. 💖

You can override the default shell by appending a custom command to the foot command line:

foot htop

💅 OPTIONS 💅

Okay so here's the whole flag lineup, bestie. Every option stays exactly as it is — no renaming, no merging, no invented shortcuts. No cap. 👑

  • -c, --config=PATH — Path to configuration file, see foot.ini(5) for details.

The configuration file is automatically passed to new terminals spawned via spawn-terminal (see foot.ini(5)). So your new terminals get the config love too. 💖

  • -C, --check-config — Verify configuration and then exit with 0 if ok, otherwise exit with 230 (see EXIT STATUS). A little vibe check for your config. ✅
  • -o, --override=[SECTION.]KEY=VALUE — Override an option set in the configuration file. If SECTION is not given, defaults to main.
  • -f, --font=FONT — Comma separated list of fonts to use, in fontconfig format (see FONT FORMAT).

The first font is the primary font. The remaining fonts are fallback fonts that will be used whenever a glyph cannot be found in the primary font.

The fallback fonts are searched in the order they appear. If a glyph cannot be found in any of the fallback fonts, the dynamic fallback list from fontconfig (for the primary font) is searched.

Default: monospace.

  • -w, --window-size-pixels=WIDTHxHEIGHT — Set initial window width and height, in pixels. Default: 700x500.
  • -W, --window-size-chars=WIDTHxHEIGHT — Set initial window width and height, in characters. Default: not set.
  • -t, --term=TERM — Value to set the environment variable TERM to (see TERMINFO and ENVIRONMENT). Default: foot.
  • -T, --title=TITLE — Initial window title. Default: foot.
  • -a, --app-id=ID — Value to set the app-id property on the Wayland window to. Default: foot (normal mode), or footclient (server mode).
  • --class=ID — Alias for --app-id.
  • toplevel-tag=TAG — 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.
  • -m, --maximized — Start in maximized mode. If both --maximized and --fullscreen are specified, the last one takes precedence.
  • -F, --fullscreen — Start in fullscreen mode. If both --maximized and --fullscreen are specified, the last one takes precedence.
  • -L, --login-shell — Start a login shell, by prepending a '-' to argv[0].
  • --pty — Display an existing pty instead of creating one. This is useful for interacting with VM consoles.

This option is not currently supported in combination with -s,--server. Sorry bestie, that's the rule. 🙈

  • -D, --working-directory=DIR — Initial working directory for the client application. Default: CWD of foot.
  • -s, --server[=PATH|FD] — Run as a server. In this mode, a single foot instance hosts multiple terminals (windows). Use footclient(1) to launch new terminals.
    • This saves some memory since for example fonts and glyph caches can be shared between the terminals.
    • It also saves upstart time since the config has already been loaded and parsed, and most importantly, fonts have already been loaded (and their glyph caches are likely to already have been populated).
    • Each terminal will have its own rendering threads, but all Wayland communication, as well as input/output to the shell, is multiplexed in the main thread. Thus, this mode might result in slightly worse performance when multiple terminals are under heavy load.
    • Also be aware that should one terminal crash, it will take all the others with it. 🫠
    • The default path is $XDG_RUNTIME_DIR/foot-$WAYLAND_DISPLAY.sock.
    • If $XDG_RUNTIME_DIR is not set, the default path is instead /tmp/foot.sock.
    • If $XDG_RUNTIME_DIR is set, but $WAYLAND_DISPLAY is not, the default path is $XDG_RUNTIME_DIR/foot.sock.
    • Note that if you change the default, you will also need to use the --server-socket option in footclient(1) and point it to your custom socket path.
    • If the argument is a number, foot will interpret it as the file descriptor of a socket provided by a supervision daemon (such as systemd or s6), and use that socket as its own.
    • Two systemd units (foot-server.{service,socket}) are provided to use that feature with systemd. To use socket activation, only enable the socket unit.
    • Note that starting foot --server as a systemd service will use the environment of the systemd user instance; thus, you'll need to import $WAYLAND_DISPLAY in it using systemctl --user import-environment WAYLAND_DISPLAY.
  • -H, --hold — Remain open after child process exits.
  • -p, --print-pid=FILE|FD — Print PID to this file, or FD, when successfully started. The file (or FD) is closed immediately after writing the PID. When a FILE has been specified, the file is unlinked at exit.

This option can only be used in combination with -s,--server.

  • -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. Default: auto.
  • -S, --log-no-syslog — Disables syslog logging. Logging is only done on stderr. This option can only be used in combination with -s,--server.
  • -v, --version — Show the version number and quit.
  • -e — Ignored; for compatibility with xterm -e.

This option was added in response to several program launchers passing -e to arbitrary terminals, under the assumption that they all implement the same semantics for it as xterm(1). Ignoring it allows foot to be invoked as e.g. foot -e man foot with the same results as with xterm, instead of producing an “invalid option” error. 💀✨

⌨️ KEYBOARD SHORTCUTS ⌨️

Okay bestie, here's the tea ☕ — these are all the keyboard shortcuts you get by default. You can literally change any of them in foot.ini(5), and there are more actions (disabled by default) hanging out in there too, so go peek at foot.ini(5) if you're curious 👀.

🌸 NORMAL MODE 🌸

  • shift+page up/page down — scroll up/down through your history, easy peasy
  • ctrl+shift+c, XF86Copy — copy whatever you've selected to the clipboard 💅
  • ctrl+shift+v, XF86Paste — paste from the clipboard
  • shift+insert — paste from the primary selection
  • ctrl+shift+r — start a scrollback search 🔍
  • ctrl++, ctrl+= — bump the font size up
  • ctrl+- — shrink the font size down
  • ctrl+0 — reset the font size back to normal
  • ctrl+shift+n — spawn a whole new terminal ✨ (and if your shell's been configured to emit the OSC 7 escape sequence, the new terminal starts off in your current working directory — chef's kiss)
  • ctrl+shift+o — activate URL mode, where you get to "launch" URLs 🚀
  • ctrl+shift+u — activate Unicode input
  • ctrl+shift+z — jump to the previous prompt that's currently not visible. Requires shell integration, no cap
  • ctrl+shift+x — jump to the next prompt. Also requires shell integration

These ones below are all about the search selection:

  • ctrl+r — search backward for the next match. If the search string is empty, it just reuses the last string you searched for (convenient!)
  • ctrl+s — search forward for the next match. Same deal: empty search string means the last searched-for string gets used
  • shift+right — extend the current selection one character to the right
  • shift+left — extend the current selection one character to the left
  • ctrl+w, ctrl+shift+right — extend the current selection (which is also the search criteria, iykyk) to the end of the word — or to the next word, if you're currently sitting on a word-separating character
  • ctrl+shift+w — same as ctrl+w, except the only word-separating characters are whitespace characters
  • ctrl+shift+left — extend the current selection to the left, all the way to the last word boundary
  • shift+down — extend the current selection down one line
  • shift+up — extend the current selection up one line
  • ctrl+v, ctrl+shift+v, ctrl+y, XF86Paste — paste from the clipboard straight into the search buffer 🫶
  • shift+insert — paste from the primary selection into the search buffer
  • escape, ctrl+g, ctrl+c — cancel the search, we're done here
  • return — finish the search and copy the current match to the primary selection. The terminal selection is kept, so you can still hit ctrl+shift+c to copy it to the clipboard 💖

And these ones are all about the search box when you're in scrollback-search mode:

  • ctrl+b — move the cursor in the search box one character to the left
  • ctrl+left, alt+b — move the cursor in the search box one word to the left
  • ctrl+f — move the cursor in the search box one character to the right
  • ctrl+right, alt+f — move the cursor in the search box one word to the right
  • Home, ctrl+a — yeet the cursor to the beginning of the input
  • End, ctrl+e — yeet the cursor to the end of the input
  • alt+backspace, ctrl+backspace — delete the word before the cursor
  • alt+delete, ctrl+delete — delete the word after the cursor
  • ctrl+u — delete from the cursor all the way back to the start of the input
  • ctrl+k — delete from the cursor all the way to the end of the input

And these last ones control scrolling in scrollback-search mode:

  • shift+page-up — scroll up/back one page in history
  • shift+page-down — scroll down/forward one page in history

🔗 URL MODE 🔗

  • t — toggle URL visibility in the jump label
  • escape, ctrl+g, ctrl+c, ctrl+d — exit URL mode without launching anything. No URL for you today 🙈

🖱️ MOUSE SHORTCUTS 🖱️

  • left, single-click — drag to select; when you let go, the selected text gets copied to the primary selection. Fair warning: this is normally disabled whenever the client has enabled mouse tracking — but you can force it by holding shift. Holding ctrl gives you a block selection instead, iconic
  • left, double-click — selects the word under the pointer (words are separated by spaces, period, comma, parenthesis etc). Hold ctrl to select everything under the pointer up to, and until, the next space characters
  • left, triple-click — selects everything between the enclosing quotes, or the entire row if you're not inside a quote
  • left, quad-click — selects the entire row, periodt
  • middle — paste from the primary selection
  • right — extend the current selection. Clicking immediately extends it, while hold-and-drag lets you interactively resize the selection
  • ctrl+right — extend the current selection, but force it to be character wise instead of depending on the original selection mode
  • wheel — scroll up/down in history
  • ctrl+wheel — increase/decrease the font size

📱 TOUCHSCREEN 📱

  • tap — emulates a mouse left button click
  • drag — scrolls up/down in history. Holding for a while before you drag (the time delay is configurable) emulates mouse dragging with the left button held down 🦋

🎀 FONT FORMAT 🎀

So the font is specified in FontConfig syntax — which is basically a colon-separated list of a font name plus font options. That's it, that's the whole vibe.

Examples, bestie:

  • Dina:weight=bold:slant=italic
  • Courier New:size=12

🌈 URLs 🌈

Foot supports URL detection — but here's where it gets different, and honestly? obsessed. Unlike a lot of other terminal emulators, where URLs get highlighted when you hover and open when you click them, foot goes full keyboard-driven. Main character energy, honestly 👑

Press ctrl+shift+o and you enter "Open URL mode", where every currently visible URL gets underlined and is associated with a "jump-label". That jump-label tells you the key sequence (like "AF") you press to activate that URL.

The key binding can, of course, be customized — like literally every other key binding in foot. See show-urls-launch and show-urls-copy in foot.ini(5).

show-urls-launch opens the URL with xdg-open by default. Wanna change that? The url-launch option's got you.

show-urls-copy is the alternative to show-urls-launch — it changes what activating a URL does. Instead of opening it, it copies it to the clipboard. Note: it's unbound by default, so you'll have to set that up yourself 💅

Oh and the jump label colors, the URL underline color, and the letters used in the jump label key sequences? All configurable. Customize away ✨

💀 ALT/META CHARACTERS 💀

By default, foot prefixes meta characters with ESC. That corresponds to XTerm's metaSendsEscape option being set to true.

This can be disabled programmatically with E[?1036l (and enabled again with E[?1036h).

When it's disabled, foot will instead set the 8:th bit of the meta character and then UTF-8 encode it. That corresponds to XTerm's eightBitMeta option being set to true.

This can also be disabled programmatically with rmm (Reset Meta Mode, E[?1034l), and enabled again with smm (Set Meta Mode, E[?1034h).

⌫ BACKSPACE ⌫

Foot transmits DEL (^?) on backspace. That corresponds to XTerm's backarrowKey option set to false, and to DECBKM being reset.

Wanna transmit BS (^H) instead? Press ctrl+backspace, bestie.

⚠️ Heads up: foot does not implement DECBKM, and the behavior described above cannot be changed. That's just how it is, no cap.

And finally — pressing alt prefixes the transmitted byte with ESC.

🔢 KEYPAD 🔢

By default, Num Lock overrides the run-time configuration keypad mode; when it's active, the keypad is always considered to be in numerical mode. This corresponds to XTerm's numLock option set to true.

In this mode, the keypad keys always send either numbers (when Num Lock is active) or cursor movement keys (up, down, left, right, page up, page down etc).

This can be disabled programmatically with E[?1035l (and enabled again with E[?1035h).

When disabled, the keypad sends custom escape sequences instead of numbers when in application mode.

⚙️ CONFIGURATION ⚙️

Foot goes looking for a configuration file in these locations, in this exact order:

  • XDG_CONFIG_HOME/foot/foot.ini (defaulting to $HOME/.config/foot/foot.ini if unset)
  • XDG_CONFIG_DIRS/foot/foot.ini (defaulting to /etc/xdg/foot/foot.ini if unset)

An example config file — with literally every option in it, and its default value all commented out — will usually be installed to /etc/xdg/foot/foot.ini. Very demure, very helpful 🎀

For more info, see foot.ini(5).

🐚 SHELL INTEGRATION 🐚

📂 Current working directory

New foot terminal instances (bound to ctrl+shift+n by default) will open in the current working directory — but only if the shell in the "parent" terminal actually reports directory changes.

How's that done? With the OSC-7 escape sequence. Most shells can be scripted to do this if they don't support it natively. Check the wiki for the details:

https://codeberg.org/dnkl/foot/wiki#user-content-spawning-new-terminal-instances-in-the-current-working-directory

🎯 Jumping between prompts

Foot can move the current viewport to focus the prompts of commands you've already executed (bound to ctrl+shift+z/x by default).

For this to actually work, the shell needs to emit an OSC-133;A (\E]133;A\E\\) sequence before each prompt.

In zsh, one way to do that is adding a precmd hook:

precmd() {
    print -Pn "\e]133;A\e\\"
}

See the wiki for details, plus examples for other shells:

https://codeberg.org/dnkl/foot/wiki#user-content-jumping-between-prompts

🚰 Piping last command's output

The pipe-command-output key binding can pipe the last command's output to an application of your choice — super similar to the other pipe-* key bindings, iykyk:

[key-bindings]
pipe-command-output=[sh -c "f=$(mktemp); cat - > $f; footclient
emacsclient -nw $f; rm $f"] Control+Shift+g

So when you press ctrl+shift+g, the last command's output gets written to a temporary file, then an emacsclient gets started in a fresh footclient instance. The temporary file is removed after that footclient instance has closed. Clean, tidy, slay ✨

For this one to work, the shell must emit an OSC-133;C (\E]133;C\E\\) sequence before the command output starts, and an OSC-133;D (\E]133;D\E\\) when the command output ends.

In fish, one way to do this is adding preexec and postexec hooks:

function foot_cmd_start --on-event fish_preexec
    echo -en "\e]133;C\e\\"
end

function foot_cmd_end --on-event fish_postexec
    echo -en "\e]133;D\e\\"
end

See the wiki for details, and examples for other shells:

https://codeberg.org/dnkl/foot/wiki#user-content-piping-last-commands-output

✨ TERMINFO ✨

Okay so bestie, here's the whole terminfo situation 💅 Client apps peep at the terminfo identifier that's sitting in the TERM environment variable (foot is the one that sets it, mwah) to figure out what your terminal can actually do.

Foot ships two terminfo definitions: foot and foot-direct, and foot is the default one, no cap.

The whole difference between them? How many colors they describe, periodt:

  • foot describes 256 colors
  • foot-direct describes 16.7 million colors (24-bit truecolor) 🌈
Lowkey important: using the foot terminfo does not limit you to 256 usable colors — apps can still send 24-bit RGB colors all day long. In fact, most applications work best with foot (yes, 24-bit colors included 💖). Using *-direct terminfo entries has legit been known to crash some ncurses applications even 😭.

But like, some applications do need a *-direct terminfo entry for their 24-bit support. Emacs is one such example 👀.

While using either foot or foot-direct is strongly recommended, you can also use e.g. xterm-256color if you want. That's actually handy when you're remoting into a system where foot's terminfo entries can't easily be installed, iykyk 🧚

And here's the cute part: terminfo entries can be installed in the user's home directory ✨ So if you don't have root access, or there's no distro package for foot's terminfo entries, you can install them manually — just copy foot and foot-direct into ~/.terminfo/f/. Slay, no sudo required 💅

🦋 XTGETTCAP 🦋

So XTGETTCAP is an escape sequence that XTerm introduced first, and Kitty also implements it (and extended it a bit too).

What it does: it lets you query the terminal for its classic, file-based terminfo definition. Like, if every application used this feature, you wouldn't even have to install foot's terminfo on the remote hosts you SSH into anymore. Iconic behavior honestly 👑

XTerm's implementation (as of XTerm-370) only supports querying key (as in keyboard keys) capabilities, plus three custom capabilities:

  • TN — terminal name
  • Co — number of colors (alias for the colors capability)
  • RGB — number of bits per color channel (different semantics from the RGB capability in file-based terminfo definitions! ⚠️)

Kitty extended this and also supports querying all integer and string capabilities.

Foot supports this too, and takes it even further — boolean capabilities are included as well 💫 Which means foot's entire terminfo can be queried via XTGETTCAP. She ate, fr fr.

Now, heads up: both Kitty and foot handle responses to multi-capability queries slightly differently compared to XTerm 👀

XTerm will send a single DCS reply, with ;-separated capability/value pairs. And there are a couple of issues with that:

  • The success/fail flag at the start of the response is always 1 (success), unless the very first queried capability is invalid.
  • XTerm will not respond at all to an invalid capability, unless it's the first one in the XTGETTCAP query.
  • XTerm will end the response at the first invalid capability.

In other words, if you send a big multi-capability query, you'll only get responses up to — but not including — the first invalid capability 😭 All the subsequent capabilities get dropped. Rough.

Kitty and foot on the other hand send one DCS response for each capability in the multi query 🎀 That way we can send a proper success/fail flag for every single queried capability. Responses for all queried capabilities are always sent, and no queries are ever dropped. Main character energy honestly.

🌸 EXIT STATUS 🌸

Foot will exit with code 230 if there's a failure in foot itself.

In all other cases, the exit code is that of the client application (i.e. the shell). Simple as that 💖

🌈 ENVIRONMENT 🌈

Variables used by foot 👑

  • SHELL — the default child process to run, when no command argument is specified and the shell option in foot.ini(5) isn't set.
  • HOME — used to determine the location of the configuration file, see foot.ini(5) for details.
  • XDG_CONFIG_HOME — used to determine the location of the configuration file, see foot.ini(5) for details.
  • XDG_CONFIG_DIRS — used to determine the location of the configuration file, see foot.ini(5) for details.
  • XDG_RUNTIME_DIR — used to construct the default PATH for the --server option, when no explicit argument is given (see above).
  • WAYLAND_DISPLAY — used to construct the default PATH for the --server option, when no explicit argument is given (see above).
  • XCURSOR_THEME — the name of the Xcursor(3) theme to use for pointers (typically set by the Wayland compositor).
  • XCURSOR_SIZE — the size to use for Xcursor(3) pointers (typically set by the Wayland compositor).

Variables set in the child process 🫶

  • TERM — terminfo/termcap identifier. Client applications use this 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 tell 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). Cute, right? ✨

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 me making sure nobody mistakes us for somebody else 💀)

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

🎀 Signals 🎀

The following signals have special meaning in foot:

  • SIGUSR1: switch to the dark color theme ([colors-dark]).
  • SIGUSR2: switch to the light color theme ([colors-light]).
Note: you can send SIGUSR1/SIGUSR2 to a foot --server process too, in which case all client instances will switch theme. And furthermore, all future client instances will also use the selected theme. Obsessed with the consistency ngl 👑

You can also send SIGUSR1/SIGUSR2 to a footclient instance, see footclient(1) for details.

😭 BUGS 😭

Please report bugs to https://codeberg.org/dnkl/foot/issues

Before you open a new issue, please search existing bug reports — both open and closed ones. Chances are someone else has already reported the same issue (it happens bestie, no shade 🫶).

The report should contain the following:

  • Foot version (foot --version).
  • Log output from foot (run foot -d info from another terminal).
  • Which Wayland compositor (and version) you're running.
  • If reporting a crash, please try to provide a bt full backtrace with symbols.
  • Steps to reproduce. The more details the better 💖

💜 IRC 💜

#foot on irc.libera.chat

⭐ SEE ALSO ⭐

foot.ini(5), footclient(1)

And that's the whole page, bestie 🎀 You just read foot(1) — source/version and date on the tin: 2026-09-08, filed under foot(1). Go forth and terminal, you're gonna slay 💅✨

📦 where this page comes from