1foot(1) General Commands Manual foot(1)
2
6 foot - Wayland terminal emulator
7
9 foot [OPTIONS]
10 foot [OPTIONS] <command> [COMMAND OPTIONS]
11 All trailing (non-option) arguments are treated as a command, and its
13 arguments, to execute (instead of the default shell).
14
16 foot is a Wayland terminal emulator. Running it without arguments will
17 start a new terminal window with your default shell.
18 You can override the default shell by appending a custom command to the
20 foot command line
21 foot sh -c "echo hello world && sleep 5"
23
25 -c,--config=PATH
26 Path to configuration file, see foot.ini(5) for details.
27 -C,--check-config
29 Verify configuration and then exit with 0 if ok, otherwise exit
30 with 230 (see EXIT STATUS).
31 -o,--override=[SECTION.]KEY=VALUE
33 Override an option set in the configuration file. If SECTION is not
34 given, defaults to main.
35 -f,--font=FONT
37 Comma separated list of fonts to use, in fontconfig format (see
38 FONT FORMAT).
39 The first font is the primary font. The remaining fonts are fall‐
41 back fonts that will be used whenever a glyph cannot be found in
42 the primary font.
43 The fallback fonts are searched in the order they appear. If a
45 glyph cannot be found in any of the fallback fonts, the dynamic
46 fallback list from fontconfig (for the primary font) is searched.
47 Default: monospace.
49 -w,--window-size-pixels=WIDTHxHEIGHT
51 Set initial window width and height, in pixels. Default: 700x500.
52 -W,--window-size-chars=WIDTHxHEIGHT
54 Set initial window width and height, in characters. Default: not
55 set.
56 -t,--term=TERM
58 Value to set the environment variable TERM to (see TERMINFO and EN‐
59 VIRONMENT). Default: foot-extra.
60 -T,--title=TITLE
62 Initial window title. Default: foot.
63 -a,--app-id=ID
65 Value to set the app-id property on the Wayland window to. Default:
66 foot (normal mode), or footclient (server mode).
67 -m,--maximized
69 Start in maximized mode. If both --maximized and --fullscreen are
70 specified, the last one takes precedence.
71 -F,--fullscreen
73 Start in fullscreen mode. If both --maximized and --fullscreen are
74 specified, the last one takes precedence.
75 -L,--login-shell
77 Start a login shell, by prepending a '-' to argv[0].
78 -D,--working-directory=DIR
80 Initial working directory for the client application. Default: CWD
81 of foot.
82 -s,--server[=PATH|FD]
84 Run as a server. In this mode, a single foot instance hosts multi‐
85 ple terminals (windows). Use footclient(1) to launch new terminals.
86 This saves some memory since for example fonts and glyph caches can
88 be shared between the terminals.
89 It also saves upstart time since the config has already been loaded
91 and parsed, and most importantly, fonts have already been loaded
92 (and their glyph caches are likely to already have been populated).
93 Each terminal will have its own rendering threads, but all Wayland
95 communication, as well as input/output to the shell, is multiplexed
96 in the main thread. Thus, this mode might result in slightly worse
97 performance when multiple terminals are under heavy load.
98 Also be aware that should one terminal crash, it will take all the
100 others with it.
101 The default path is $XDG_RUNTIME_DIR/foot-$WAYLAND_DISPLAY.sock.
103 If $XDG_RUNTIME_DIR is not set, the default path is instead
105 /tmp/foot.sock.
106 If $XDG_RUNTIME_DIR is set, but $WAYLAND_DISPLAY is not, the de‐
108 fault path is $XDG_RUNTIME_DIR/foot.sock.
109 Note that if you change the default, you will also need to use the
111 --server-socket option in footclient(1) and point it to your custom
112 socket path.
113 If the argument is a number, foot will interpret it as the file de‐
115 scriptor of a socket provided by a supervision daemon (such as sys‐
116 temd or s6), and use that socket as it's own.
117 Two systemd units (foot-server.{service,socket}) are provided to
119 use that feature with systemd. To use socket activation, only en‐
120 able the socket unit.
121 Note that starting foot --server as a systemd service will use the
123 environment of the systemd user instance; thus, you'll need to im‐
124 port $WAYLAND_DISPLAY in it using systemctl --user import-environ‐
125 ment WAYLAND_DISPLAY.
126 -H,--hold
128 Remain open after child process exits.
129 -p,--print-pid=FILE|FD
131 Print PID to this file, or FD, when successfully started. The file
132 (or FD) is closed immediately after writing the PID. When a FILE as
133 been specified, the file is unlinked at exit.
134 This option can only be used in combination with -s,--server.
136 -d,--log-level={info,warning,error,none}
138 Log level, used both for log output on stderr as well as syslog.
139 Default: warning.
140 -l,--log-colorize=[{never,always,auto}]
142 Enables or disables colorization of log output on stderr. Default:
143 auto.
144 -S,--log-no-syslog
146 Disables syslog logging. Logging is only done on stderr. This op‐
147 tion can only be used in combination with -s,--server.
148 -v,--version
150 Show the version number and quit.
151 -e
153 Ignored; for compatibility with xterm -e.
154 This option was added in response to several program launchers
156 passing -e to arbitrary terminals, under the assumption that they
157 all implement the same semantics for it as xterm(1). Ignoring it
158 allows foot to be invoked as e.g. foot -e man foot with the same
159 results as with xterm, instead of producing an "invalid option" er‐
160 ror.
161
163 The following keyboard shortcuts are available by default. They can be
164 changed in foot.ini(5). There are also more actions (disabled by de‐
165 fault) available; see foot.ini(5).
166 NORMAL MODE
168 shift+page up/page down
169 Scroll up/down in history
170 ctrl+shift+c, XF86Copy
172 Copy selected text to the clipboard
173 ctrl+shift+v, XF86Paste
175 Paste from clipboard
176 shift+insert
178 Paste from the primary selection.
179 ctrl+shift+r
181 Start a scrollback search
182 ctrl++, ctrl+=
184 Increase font size by 0.5pt
185 ctrl+-
187 Decrease font size by 0.5pt
188 ctrl+0
190 Reset font size
191 ctrl+shift+n
193 Spawn a new terminal. If the shell has been configured to emit the
194 OSC 7 escape sequence, the new terminal will start in the current
195 working directory.
196 ctrl+shift+o
198 Activate URL mode, allowing you to "launch" URLs.
199 ctrl+shift+u
201 Activate Unicode input.
202 ctrl+shift+z
204 Jump to the previous, currently not visible, prompt. Requires shell
205 integration.
206 ctrl+shift+x
208 Jump to the next prompt. Requires shell integration.
209 SCROLLBACK SEARCH
211 ctrl+r
212 Search backward for the next match. If the search string is empty,
213 the last searched-for string is used.
214 ctrl+s
216 Search forward for the next match. If the search string is empty,
217 the last searched-for string is used.
218 ctrl+w
220 Extend current selection (and thus the search criteria) to the end
221 of the word, or the next word if currently at a word separating
222 character.
223 ctrl+shift+w
225 Same as ctrl+w, except that the only word separating characters are
226 whitespace characters.
227 ctrl+v, ctrl+shift+v, ctrl+y, XF86Paste
229 Paste from clipboard into the search buffer.
230 shift+insert
232 Paste from primary selection into the search buffer.
233 escape, ctrl+g, ctrl+c
235 Cancel the search
236 return
238 Finish the search and copy the current match to the primary selec‐
239 tion. The terminal selection is kept, allowing you to press
240 ctrl+shift+c to copy it to the clipboard.
241 URL MODE
243 t
244 Toggle URL visibility in jump label.
245 escape, ctrl+g, ctrl+c, ctrl+d
247 Exit URL mode without launching a URL.
248 MOUSE SHORTCUTS
250 left, single-click
251 Drag to select; when released, the selected text is copied to the
252 primary selection. This feature is normally disabled whenever the
253 client has enabled mouse tracking, but can be forced by holding
254 shift.
255 Holding ctrl will create a block selection.
257 left, double-click
259 Selects the word (separated by spaces, period, comma, parenthesis
260 etc) under the pointer. Hold ctrl to select everything under the
261 pointer up to, and until, the next space characters.
262 left, triple-click
264 Selects the entire row
265 middle
267 Paste from the primary selection
268 right
270 Extend current selection. Clicking immediately extends the selec‐
271 tion, while hold-and-drag allows you to interactively resize the
272 selection.
273 wheel
275 Scroll up/down in history
276 TOUCHSCREEN
278 tap
279 Emulates mouse left button click.
280 drag
282 Scrolls up/down in history.
283 Holding for a while before dragging (time delay can be configured)
285 emulates mouse dragging with left button held.
286
288 The font is specified in FontConfig syntax. That is, a colon-separated
289 list of font name and font options.
290 Examples:
292 • Dina:weight=bold:slant=italic
293 • Courier New:size=12
294
297 Foot supports URL detection. But, unlike many other terminal emulators,
298 where URLs are highlighted when they are hovered and opened by clicking
299 on them, foot uses a keyboard driven approach.
300 Pressing ctrl+shift+o enters “Open URL mode”, where all currently visi‐
302 ble URLs are underlined, and is associated with a “jump-label”. The
303 jump-label indicates the key sequence (e.g. ”AF”) to use to activate
304 the URL.
305 The key binding can, of course, be customized, like all other key bind‐
307 ings in foot. See show-urls-launch and show-urls-copy in foot.ini(5).
308 show-urls-launch by default opens the URL with xdg-open. This can be
310 changed with the url-launch option.
311 show-urls-copy is an alternative to show-urls-launch, that changes what
313 activating a URL does; instead of opening it, it copies it to the clip‐
314 board. It is unbound by default.
315 Jump label colors, the URL underline color, and the letters used in the
317 jump label key sequences can be configured.
318
320 By default, foot prefixes meta characters with ESC. This corresponds to
321 XTerm's metaSendsEscape option set to true.
322 This can be disabled programmatically with E[?1036l (and enabled again
324 with E[?1036h).
325 When disabled, foot will instead set the 8:th bit of meta character and
327 then UTF-8 encode it. This corresponds to XTerm's eightBitMeta option
328 set to true.
329 This can also be disabled programmatically with rmm (Reset Meta Mode,
331 E[?1034l), and enabled again with smm (Set Meta Mode, E[?1034h).
332
334 Foot transmits DEL (^?) on backspace. This corresponds to XTerm's
335 backarrowKey option set to false, and to DECBKM being reset.
336 To instead transmit BS (^H), press ctrl+backspace.
338 Note that foot does not implement DECBKM, and that the behavior de‐
340 scribed above cannot be changed.
341 Finally, pressing alt will prefix the transmitted byte with ESC.
343
345 By default, Num Lock overrides the run-time configuration keypad mode;
346 when active, the keypad is always considered to be in numerical mode.
347 This corresponds to XTerm's numLock option set to true.
348 In this mode, the keypad keys always sends either numbers (Num Lock is
350 active) or cursor movement keys (up, down, left, right, page up, page
351 down etc).
352 This can be disabled programmatically with E[?1035l (and enabled again
354 with E[?1035h).
355 When disabled, the keypad sends custom escape sequences instead of num‐
357 bers, when in application mode.
358
360 foot will search for a configuration file in the following locations,
361 in this order:
362 • XDG_CONFIG_HOME/foot/foot.ini (defaulting to $HOME/.con‐
364 fig/foot/foot.ini if unset)
365 • XDG_CONFIG_DIRS/foot/foot.ini (defaulting to
366 /etc/xdg/foot/foot.ini if unset)
367 An example configuration file containing all options with their default
370 value commented out will usually be installed to
371 /etc/xdg/foot/foot.ini.
372 For more information, see foot.ini(5).
374
376 Current working directory
377 New foot terminal instances (bound to ctrl+shift+n by default) will
378 open in the current working directory, if the shell in the “parent”
379 terminal reports directory changes.
380 This is done with the OSC-7 escape sequence. Most shells can be
382 scripted to do this, if they do not support it natively. See the wiki
383 (https://codeberg.org/dnkl/foot/wiki#user-content-spawning-new-termi‐
384 nal-instances-in-the-current-working-directory) for details.
385 Jumping between prompts
387 Foot can move the current viewport to focus prompts of already executed
388 commands (bound to ctrl+shift+z/x by default).
389 For this to work, the shell needs to emit an OSC-133;A (\E]133;A\E\\)
391 sequence before each prompt.
392 In zsh, one way to do this is to add a precmd hook:
394 precmd() {
396 print -Pn "\e]133;A\e\\"
397 }
398 See the wiki (https://codeberg.org/dnkl/foot/wiki#user-content-jumping-
400 between-prompts) for details, and examples for other shells.
401
403 Client applications use the terminfo identifier specified by the envi‐
404 ronment variable TERM (set by foot) to determine terminal capabilities.
405 Foot has two terminfo definitions: foot and foot-direct, with foot be‐
407 ing the default.
408 The difference between the two is in the number of colors they de‐
410 scribe; foot describes 256 colors and foot-direct 16.7 million colors
411 (24-bit truecolor).
412 Note that using the foot terminfo does not limit the number of usable
414 colors to 256; applications can still use 24-bit RGB colors. In fact,
415 most applications work best with foot (including 24-bit colors). Using
416 *-direct terminfo entries has been known to crash some ncurses applica‐
417 tions even.
418 There are however applications that need a *-direct terminfo entry for
420 24-bit support. Emacs is one such example.
421 While using either foot or foot-direct is strongly recommended, it is
423 possible to use e.g. xterm-256color as well. This can be useful when
424 remoting to a system where foot's terminfo entries cannot easily be in‐
425 stalled.
426 Note that terminfo entries can be installed in the user's home direc‐
428 tory. I.e. if you do not have root access, or if there is no distro
429 package for foot's terminfo entries, you can install foot's terminfo
430 entries manually, by copying foot and foot-direct to ~/.terminfo/f/.
431
433 XTGETTCAP is an escape sequence initially introduced by XTerm, and also
434 implemented (and extended, to some degree) by Kitty.
435 It allows querying the terminal for terminfo classic, file-based, ter‐
437 minfo definition. For example, if all applications used this feature,
438 you would no longer have to install foot’s terminfo on remote hosts you
439 SSH into.
440 XTerm’s implementation (as of XTerm-370) only supports querying key (as
442 in keyboard keys) capabilities, and three custom capabilities:
443 • TN - terminal name
445 • Co - number of colors (alias for the colors capability)
446 • RGB - number of bits per color channel (different semantics from
447 the RGB capability in file-based terminfo definitions!).
448 Kitty has extended this, and also supports querying all integer and
451 string capabilities.
452 Foot supports this, and extends it even further, to also include bool‐
454 ean capabilities. This means foot’s entire terminfo can be queried via
455 XTGETTCAP.
456 Note that both Kitty and foot handles responses to multi-capability
458 queries slightly differently, compared to XTerm.
459 XTerm will send a single DCS reply, with ;-separated capability/value
461 pairs. There are a couple of issues with this:
462 • The success/fail flag in the beginning of the response is always 1
464 (success), unless the very first queried capability is invalid.
465 • XTerm will not respond at all to an invalid capability, unless it’s
466 the first one in the XTGETTCAP query.
467 • XTerm will end the response at the first invalid capability.
468 In other words, if you send a large multi-capability query, you will
471 only get responses up to, but not including, the first invalid capabil‐
472 ity. All subsequent capabilities will be dropped.
473 Kitty and foot on the other hand, send one DCS response for each capa‐
475 bility in the multi query. This allows us to send a proper success/fail
476 flag for each queried capability. Responses for all queried capabili‐
477 ties are always sent. No queries are ever dropped.
478
480 Foot will exit with code 230 if there is a failure in foot itself.
481 In all other cases, the exit code is that of the client application
483 (i.e. the shell).
484
486 Variables used by foot
487 SHELL
488 The default child process to run, when no command argument is spec‐
489 ified and the shell option in foot.ini(5) is not set.
490 HOME
492 Used to determine the location of the configuration file, see
493 foot.ini(5) for details.
494 XDG_CONFIG_HOME
496 Used to determine the location of the configuration file, see
497 foot.ini(5) for details.
498 XDG_CONFIG_DIRS
500 Used to determine the location of the configuration file, see
501 foot.ini(5) for details.
502 XDG_RUNTIME_DIR
504 Used to construct the default PATH for the --server option, when no
505 explicit argument is given (see above).
506 WAYLAND_DISPLAY
508 Used to construct the default PATH for the --server option, when no
509 explicit argument is given (see above).
510 XCURSOR_THEME
512 The name of the Xcursor(3) theme to use for pointers (typically set
513 by the Wayland compositor).
514 XCURSOR_SIZE
516 The size to use for Xcursor(3) pointers (typically set by the Way‐
517 land compositor).
518 Variables set in the child process
520 TERM
521 terminfo/termcap identifier. This is used by client applications to
522 determine which capabilities a terminal supports. The value is set
523 according to either the --term command-line option or the term con‐
524 fig option in foot.ini(5).
525 PWD
527 Current working directory (at the time of launching foot)
528 COLORTERM
530 This variable is set to truecolor, to indicate to client applica‐
531 tions that 24-bit RGB colors are supported.
532 In addition to the variables listed above, custom environment variables
534 may be defined in foot.ini(5).
535
537 Please report bugs to https://codeberg.org/dnkl/foot/issues
538 Before you open a new issue, please search existing bug reports, both
540 open and closed ones. Chances are someone else has already reported the
541 same issue.
542 The report should contain the following:
544 • Foot version (foot --version).
546 • Log output from foot (run foot -d info from another terminal).
547 • Which Wayland compositor (and version) you are running.
548 • If reporting a crash, please try to provide a bt full backtrace
549 with symbols.
550 • Steps to reproduce. The more details the better.
551
554 #foot on irc.libera.chat
555
557 foot.ini(5), footclient(1)
558 2023-08-08 foot(1)