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.
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.
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. They need to be instantiated with
120 the value of $WAYLAND_DISPLAY (multiples instances can co-exists).
121 Note that starting foot --server as a systemd service will use the
123 environment of the systemd user instance; thus, if you need spe‐
124 cific environment variables, you'll need to import them using sys‐
125 temctl --user import-environment or use a drop-in for the foot-
126 server service.
127 -H,--hold
129 Remain open after child process exits.
130 -p,--print-pid=FILE|FD
132 Print PID to this file, or FD, when successfully started. The file
133 (or FD) is closed immediately after writing the PID. When a FILE as
134 been specified, the file is unlinked at exit.
135 This option can only be used in combination with -s,--server.
137 -d,--log-level={info,warning,error,none}
139 Log level, used both for log output on stderr as well as syslog.
140 Default: info.
141 -l,--log-colorize=[{never,always,auto}]
143 Enables or disables colorization of log output on stderr. Default:
144 auto.
145 -S,--log-no-syslog
147 Disables syslog logging. Logging is only done on stderr. This op‐
148 tion can only be used in combination with -s,--server.
149 -v,--version
151 Show the version number and quit.
152 -e
154 Ignored; for compatibility with xterm -e.
155 This option was added in response to several program launchers
157 passing -e to arbitrary terminals, under the assumption that they
158 all implement the same semantics for it as xterm(1). Ignoring it
159 allows foot to be invoked as e.g. foot -e man foot with the same
160 results as with xterm, instead of producing an "invalid option" er‐
161 ror.
162
164 The following keyboard shortcuts are available by default. They can be
165 changed in foot.ini(5). There are also more actions (disabled by de‐
166 fault) available; see foot.ini(5).
167 NORMAL MODE
169 shift+page up/page down
170 Scroll up/down in history
171 ctrl+shift+c, XF86Copy
173 Copy selected text to the clipboard
174 ctrl+shift+v, XF86Paste
176 Paste from clipboard
177 shift+insert
179 Paste from the primary selection.
180 ctrl+shift+r
182 Start a scrollback search
183 ctrl++, ctrl+=
185 Increase font size by 0.5pt
186 ctrl+-
188 Decrease font size by 0.5pt
189 ctrl+0
191 Reset font size
192 ctrl+shift+n
194 Spawn a new terminal. If the shell has been configured to emit the
195 OSC 7 escape sequence, the new terminal will start in the current
196 working directory.
197 ctrl+shift+u
199 Activate URL mode, allowing you to "launch" URLs.
200 ctrl+shift+z
202 Jump to the previous, currently not visible, prompt. Requires shell
203 integration.
204 ctrl+shift+x
206 Jump to the next prompt. Requires shell integration.
207 SCROLLBACK SEARCH
209 ctrl+r
210 Search backward for the next match. If the search string is empty,
211 the last searched-for string is used.
212 ctrl+s
214 Search forward for the next match. If the search string is empty,
215 the last searched-for string is used.
216 ctrl+w
218 Extend current selection (and thus the search criteria) to the end
219 of the word, or the next word if currently at a word separating
220 character.
221 ctrl+shift+w
223 Same as ctrl+w, except that the only word separating characters are
224 whitespace characters.
225 ctrl+v, ctrl+shift+v, ctrl+y, XF86Paste
227 Paste from clipboard into the search buffer.
228 shift+insert
230 Paste from primary selection into the search buffer.
231 escape, ctrl+g, ctrl+c
233 Cancel the search
234 return
236 Finish the search and copy the current match to the primary selec‐
237 tion. The terminal selection is kept, allowing you to press
238 ctrl+shift+c to copy it to the clipboard.
239 URL MODE
241 t
242 Toggle URL visibility in jump label.
243 escape, ctrl+g, ctrl+c, ctrl+d
245 Exit URL mode without launching a URL.
246 MOUSE SHORTCUTS
248 left, single-click
249 Drag to select; when released, the selected text is copied to the
250 primary selection. This feature is normally disabled whenever the
251 client has enabled mouse tracking, but can be forced by holding
252 shift.
253 Holding ctrl will create a block selection.
255 left, double-click
257 Selects the word (separated by spaces, period, comma, parenthesis
258 etc) under the pointer. Hold ctrl to select everything under the
259 pointer up to, and until, the next space characters.
260 left, triple-click
262 Selects the entire row
263 middle
265 Paste from the primary selection
266 right
268 Extend current selection. Clicking immediately extends the selec‐
269 tion, while hold-and-drag allows you to interactively resize the
270 selection.
271 wheel
273 Scroll up/down in history
274
276 The font is specified in FontConfig syntax. That is, a colon-separated
277 list of font name and font options.
278 Examples:
280 • Dina:weight=bold:slant=italic
281 • Courier New:size=12
282
285 Foot supports URL detection. But, unlike many other terminal emulators,
286 where URLs are highlighted when they are hovered and opened by clicking
287 on them, foot uses a keyboard driven approach.
288 Pressing ctrl+shift+u enters “URL mode”, where all currently visible
290 URLs are underlined, and is associated with a “jump-label”. The jump-
291 label indicates the key sequence (e.g. ”AF”) to use to activate the
292 URL.
293 The key binding can, of course, be customized, like all other key bind‐
295 ings in foot. See show-urls-launch and show-urls-copy in foot.ini(5).
296 show-urls-launch by default opens the URL with xdg-open. This can be
298 changed with the url-launch option.
299 show-urls-copy is an alternative to show-urls-launch, that changes what
301 activating a URL does; instead of opening it, it copies it to the clip‐
302 board. It is unbound by default.
303 Jump label colors, the URL underline color, and the letters used in the
305 jump label key sequences can be configured.
306
308 By default, foot prefixes meta characters with ESC. This corresponds to
309 XTerm's metaSendsEscape option set to true.
310 This can be disabled programmatically with E[?1036l (and enabled again
312 with E[?1036h).
313 When disabled, foot will instead set the 8:th bit of meta character and
315 then UTF-8 encode it. This corresponds to XTerm's eightBitMeta option
316 set to true.
317 This can also be disabled programmatically with rmm (Reset Meta Mode,
319 E[?1034l), and enabled again with smm (Set Meta Mode, E[?1034h).
320
322 Foot transmits DEL (^?) on backspace. This corresponds to XTerm's
323 backarrowKey option set to false, and to DECBKM being reset.
324 To instead transmit BS (^H), press ctrl+backspace.
326 Note that foot does not implement DECBKM, and that the behavior de‐
328 scribed above cannot be changed.
329 Finally, pressing alt will prefix the transmitted byte with ESC.
331
333 By default, Num Lock overrides the run-time configuration keypad mode;
334 when active, the keypad is always considered to be in numerical mode.
335 This corresponds to XTerm's numLock option set to true.
336 In this mode, the keypad keys always sends either numbers (Num Lock is
338 active) or cursor movement keys (up, down, left, right, page up, page
339 down etc).
340 This can be disabled programmatically with E[?1035l (and enabled again
342 with E[?1035h).
343 When disabled, the keypad sends custom escape sequences instead of num‐
345 bers, when in application mode.
346
348 foot will search for a configuration file in the following locations,
349 in this order:
350 • XDG_CONFIG_HOME/foot/foot.ini (defaulting to $HOME/.con‐
352 fig/foot/foot.ini if unset)
353 • XDG_CONFIG_DIRS/foot/foot.ini (defaulting to
354 /etc/xdg/foot/foot.ini if unset)
355 An example configuration file containing all options with their default
358 value commented out will usually be installed to
359 /etc/xdg/foot/foot.ini.
360 For more information, see foot.ini(5).
362
364 Current working directory
365 New foot terminal instances (bound to ctrl+shift+n by default) will
366 open in the current working directory, if the shell in the “parent”
367 terminal reports directory changes.
368 This is done with the OSC-7 escape sequence. Most shells can be
370 scripted to do this, if they do not support it natively. See the wiki
371 (https://codeberg.org/dnkl/foot/wiki#user-content-spawning-new-termi‐
372 nal-instances-in-the-current-working-directory) for details.
373 Jumping between prompts
375 Foot can move the current viewport to focus prompts of already executed
376 commands (bound to ctrl+shift+z/x by default).
377 For this to work, the shell needs to emit an OSC-133;A (\E]133;A\E\\)
379 sequence before each prompt.
380 In zsh, one way to do this is to add a precmd hook:
382 precmd() {
384 print -Pn "\e]133;A\e\\"
385 }
386 See the wiki (https://codeberg.org/dnkl/foot/wiki#user-content-jumping-
388 between-prompts) for details, and examples for other shells.
389
391 Client applications use the terminfo identifier specified by the envi‐
392 ronment variable TERM (set by foot) to determine terminal capabilities.
393 Foot has two terminfo definitions: foot and foot-direct, with foot be‐
395 ing the default.
396 The difference between the two is in the number of colors they de‐
398 scribe; foot describes 256 colors and foot-direct 16.7 million colors
399 (24-bit truecolor).
400 Note that using the foot terminfo does not limit the number of usable
402 colors to 256; applications can still use 24-bit RGB colors. In fact,
403 most applications work best with foot (including 24-bit colors). Using
404 *-direct terminfo entries has been known to crash some ncurses applica‐
405 tions even.
406 There are however applications that need a *-direct terminfo entry for
408 24-bit support. Emacs is one such example.
409 While using either foot or foot-direct is strongly recommended, it is
411 possible to use e.g. xterm-256color as well. This can be useful when
412 remoting to a system where foot's terminfo entries cannot easily be in‐
413 stalled.
414 Note that terminfo entries can be installed in the user's home direc‐
416 tory. I.e. if you do not have root access, or if there is no distro
417 package for foot's terminfo entries, you can install foot's terminfo
418 entries manually, by copying foot and foot-direct to ~/.terminfo/f/.
419
421 XTGETTCAP is an escape sequence initially introduced by XTerm, and also
422 implemented (and extended, to some degree) by Kitty.
423 It allows querying the terminal for terminfo classic, file-based, ter‐
425 minfo definition. For example, if all applications used this feature,
426 you would no longer have to install foot’s terminfo on remote hosts you
427 SSH into.
428 XTerm’s implementation (as of XTerm-370) only supports querying key (as
430 in keyboard keys) capabilities, and three custom capabilities:
431 • TN - terminal name
433 • Co - number of colors (alias for the colors capability)
434 • RGB - number of bits per color channel (different semantics from
435 the RGB capability in file-based terminfo definitions!).
436 Kitty has extended this, and also supports querying all integer and
439 string capabilities.
440 Foot supports this, and extends it even further, to also include bool‐
442 ean capabilities. This means foot’s entire terminfo can be queried via
443 XTGETTCAP.
444 Note that both Kitty and foot handles responses to multi-capability
446 queries slightly differently, compared to XTerm.
447 XTerm will send a single DCS reply, with ;-separated capability/value
449 pairs. There are a couple of issues with this:
450 • The success/fail flag in the beginning of the response is always 1
452 (success), unless the very first queried capability is invalid.
453 • XTerm will not respond at all to an invalid capability, unless it’s
454 the first one in the XTGETTCAP query.
455 • XTerm will end the response at the first invalid capability.
456 In other words, if you send a large multi-capability query, you will
459 only get responses up to, but not including, the first invalid capabil‐
460 ity. All subsequent capabilities will be dropped.
461 Kitty and foot on the other hand, send one DCS response for each capa‐
463 bility in the multi query. This allows us to send a proper success/fail
464 flag for each queried capability. Responses for all queried capabili‐
465 ties are always sent. No queries are ever dropped.
466
468 Foot will exit with code 230 if there is a failure in foot itself.
469 In all other cases, the exit code is that of the client application
471 (i.e. the shell).
472
474 Variables used by foot
475 SHELL
476 The default child process to run, when no command argument is spec‐
477 ified and the shell option in foot.ini(5) is not set.
478 HOME
480 Used to determine the location of the configuration file, see
481 foot.ini(5) for details.
482 XDG_CONFIG_HOME
484 Used to determine the location of the configuration file, see
485 foot.ini(5) for details.
486 XDG_CONFIG_DIRS
488 Used to determine the location of the configuration file, see
489 foot.ini(5) for details.
490 XDG_RUNTIME_DIR
492 Used to construct the default PATH for the --server option, when no
493 explicit argument is given (see above).
494 WAYLAND_DISPLAY
496 Used to construct the default PATH for the --server option, when no
497 explicit argument is given (see above).
498 XCURSOR_THEME
500 The name of the Xcursor(3) theme to use for pointers (typically set
501 by the Wayland compositor).
502 XCURSOR_SIZE
504 The size to use for Xcursor(3) pointers (typically set by the Way‐
505 land compositor).
506 Variables set in the child process
508 TERM
509 terminfo/termcap identifier. This is used by client applications to
510 determine which capabilities a terminal supports. The value is set
511 according to either the --term command-line option or the term con‐
512 fig option in foot.ini(5).
513 COLORTERM
515 This variable is set to truecolor, to indicate to client applica‐
516 tions that 24-bit RGB colors are supported.
517 In addition to the variables listed above, custom environment variables
519 may be defined in foot.ini(5).
520
522 Please report bugs to https://codeberg.org/dnkl/foot/issues
523 Before you open a new issue, please search existing bug reports, both
525 open and closed ones. Chances are someone else has already reported the
526 same issue.
527 The report should contain the following:
529 • Foot version (foot --version).
531 • Log output from foot (start foot from another terminal).
532 • Which Wayland compositor (and version) you are running.
533 • If reporting a crash, please try to provide a bt full backtrace
534 with symbols.
535 • Steps to reproduce. The more details the better.
536
539 #foot on irc.libera.chat
540
542 foot.ini(5), footclient(1)
543 2022-08-31 foot(1)