1foot(1)                     General Commands Manual                    foot(1)
2
3
4

NAME

6       foot - Wayland terminal emulator
7

SYNOPSIS

9       foot [OPTIONS]
10       foot [OPTIONS] <command> [COMMAND OPTIONS]
11
12       All trailing (non-option) arguments are treated as a command, and its
13       arguments, to execute (instead of the default shell).
14

DESCRIPTION

16       foot is a Wayland terminal emulator. Running it without arguments will
17       start a new terminal window with your default shell.
18
19       You can override the default shell by appending a custom command to the
20       foot command line
21
22           foot sh -c "echo hello world && sleep 5"
23

OPTIONS

25       -c,--config=PATH
26           Path to configuration file, see foot.ini(5) for details.
27
28       -C,--check-config
29           Verify configuration and then exit with 0 if ok, otherwise exit
30           with 230 (see EXIT STATUS).
31
32       -o,--override=[SECTION.]KEY=VALUE
33           Override an option set in the configuration file. If SECTION is not
34           given, defaults to main.
35
36       -f,--font=FONT
37           Comma separated list of fonts to use, in fontconfig format (see
38           FONT FORMAT).
39
40           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
44           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
48           Default: monospace.
49
50       -w,--window-size-pixels=WIDTHxHEIGHT
51           Set initial window width and height, in pixels. Default: 700x500.
52
53       -W,--window-size-chars=WIDTHxHEIGHT
54           Set initial window width and height, in characters. Default: not
55           set.
56
57       -t,--term=TERM
58           Value to set the environment variable TERM to (see TERMINFO and EN‐
59           VIRONMENT). Default: foot.
60
61       -T,--title=TITLE
62           Initial window title. Default: foot.
63
64       -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
68       -m,--maximized
69           Start in maximized mode. If both --maximized and --fullscreen are
70           specified, the last one takes precedence.
71
72       -F,--fullscreen
73           Start in fullscreen mode. If both --maximized and --fullscreen are
74           specified, the last one takes precedence.
75
76       -L,--login-shell
77           Start a login shell, by prepending a '-' to argv[0].
78
79       -D,--working-directory=DIR
80           Initial working directory for the client application. Default: CWD
81           of foot.
82
83       -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
87           This saves some memory since for example fonts and glyph caches can
88           be shared between the terminals.
89
90           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
94           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
99           Also be aware that should one terminal crash, it will take all the
100           others with it.
101
102           The default path is $XDG_RUNTIME_DIR/foot-$WAYLAND_DISPLAY.sock.
103
104           If $XDG_RUNTIME_DIR is not set, the default path is instead
105           /tmp/foot.sock.
106
107           If $XDG_RUNTIME_DIR is set, but $WAYLAND_DISPLAY is not, the de‐
108           fault path is $XDG_RUNTIME_DIR/foot.sock.
109
110           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
114           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
118           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
122           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
127       -H,--hold
128           Remain open after child process exits.
129
130       -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
135           This option can only be used in combination with -s,--server.
136
137       -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
141       -l,--log-colorize=[{never,always,auto}]
142           Enables or disables colorization of log output on stderr. Default:
143           auto.
144
145       -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
149       -v,--version
150           Show the version number and quit.
151
152       -e
153           Ignored; for compatibility with xterm -e.
154
155           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

KEYBOARD SHORTCUTS

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
167   NORMAL MODE
168       shift+page up/page down
169           Scroll up/down in history
170
171       ctrl+shift+c, XF86Copy
172           Copy selected text to the clipboard
173
174       ctrl+shift+v, XF86Paste
175           Paste from clipboard
176
177       shift+insert
178           Paste from the primary selection.
179
180       ctrl+shift+r
181           Start a scrollback search
182
183       ctrl++, ctrl+=
184           Increase font size by 0.5pt
185
186       ctrl+-
187           Decrease font size by 0.5pt
188
189       ctrl+0
190           Reset font size
191
192       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
197       ctrl+shift+o
198           Activate URL mode, allowing you to "launch" URLs.
199
200       ctrl+shift+u
201           Activate Unicode input.
202
203       ctrl+shift+z
204           Jump to the previous, currently not visible, prompt. Requires shell
205           integration.
206
207       ctrl+shift+x
208           Jump to the next prompt. Requires shell integration.
209
210   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
215       ctrl+s
216           Search forward for the next match. If the search string is empty,
217           the last searched-for string is used.
218
219       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
224       ctrl+shift+w
225           Same as ctrl+w, except that the only word separating characters are
226           whitespace characters.
227
228       ctrl+v, ctrl+shift+v, ctrl+y, XF86Paste
229           Paste from clipboard into the search buffer.
230
231       shift+insert
232           Paste from primary selection into the search buffer.
233
234       escape, ctrl+g, ctrl+c
235           Cancel the search
236
237       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
242   URL MODE
243       t
244           Toggle URL visibility in jump label.
245
246       escape, ctrl+g, ctrl+c, ctrl+d
247           Exit URL mode without launching a URL.
248
249   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
256           Holding ctrl will create a block selection.
257
258       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
263       left, triple-click
264           Selects the entire row
265
266       middle
267           Paste from the primary selection
268
269       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
274       wheel
275           Scroll up/down in history
276
277   TOUCHSCREEN
278       tap
279           Emulates mouse left button click.
280
281       drag
282           Scrolls up/down in history.
283
284           Holding for a while before dragging (time delay can be configured)
285           emulates mouse dragging with left button held.
286

FONT FORMAT

288       The font is specified in FontConfig syntax. That is, a colon-separated
289       list of font name and font options.
290
291       Examples:
292       •   Dina:weight=bold:slant=italic
293       •   Courier New:size=12
294
295

URLs

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
301       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
306       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
309       show-urls-launch by default opens the URL with xdg-open. This can be
310       changed with the url-launch option.
311
312       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
316       Jump label colors, the URL underline color, and the letters used in the
317       jump label key sequences can be configured.
318

ALT/META CHARACTERS

320       By default, foot prefixes meta characters with ESC. This corresponds to
321       XTerm's metaSendsEscape option set to true.
322
323       This can be disabled programmatically with E[?1036l (and enabled again
324       with E[?1036h).
325
326       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
330       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

BACKSPACE

334       Foot transmits DEL (^?) on backspace. This corresponds to XTerm's
335       backarrowKey option set to false, and to DECBKM being reset.
336
337       To instead transmit BS (^H), press ctrl+backspace.
338
339       Note that foot does not implement DECBKM, and that the behavior de‐
340       scribed above cannot be changed.
341
342       Finally, pressing alt will prefix the transmitted byte with ESC.
343

KEYPAD

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
349       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
353       This can be disabled programmatically with E[?1035l (and enabled again
354       with E[?1035h).
355
356       When disabled, the keypad sends custom escape sequences instead of num‐
357       bers, when in application mode.
358

CONFIGURATION

360       foot will search for a configuration file in the following locations,
361       in this order:
362
363XDG_CONFIG_HOME/foot/foot.ini (defaulting to $HOME/.con‐
364               fig/foot/foot.ini if unset)
365XDG_CONFIG_DIRS/foot/foot.ini (defaulting to
366               /etc/xdg/foot/foot.ini if unset)
367
368
369       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
373       For more information, see foot.ini(5).
374

SHELL INTEGRATION

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
381       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
386   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
390       For this to work, the shell needs to emit an OSC-133;A (\E]133;A\E\\)
391       sequence before each prompt.
392
393       In zsh, one way to do this is to add a precmd hook:
394
395           precmd() {
396               print -Pn "\e]133;A\e\\"
397           }
398
399       See the wiki (https://codeberg.org/dnkl/foot/wiki#user-content-jumping-
400       between-prompts) for details, and examples for other shells.
401

TERMINFO

403       Client applications use the terminfo identifier specified by the envi‐
404       ronment variable TERM (set by foot) to determine terminal capabilities.
405
406       Foot has two terminfo definitions: foot and foot-direct, with foot be‐
407       ing the default.
408
409       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
413       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
419       There are however applications that need a *-direct terminfo entry for
420       24-bit support. Emacs is one such example.
421
422       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
427       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

XTGETTCAP

433       XTGETTCAP is an escape sequence initially introduced by XTerm, and also
434       implemented (and extended, to some degree) by Kitty.
435
436       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
441       XTerm’s implementation (as of XTerm-370) only supports querying key (as
442       in keyboard keys) capabilities, and three custom capabilities:
443
444       •   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
449
450       Kitty has extended this, and also supports querying all integer and
451       string capabilities.
452
453       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
457       Note that both Kitty and foot handles responses to multi-capability
458       queries slightly differently, compared to XTerm.
459
460       XTerm will send a single DCS reply, with ;-separated capability/value
461       pairs. There are a couple of issues with this:
462
463       •   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
469
470       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
474       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

EXIT STATUS

480       Foot will exit with code 230 if there is a failure in foot itself.
481
482       In all other cases, the exit code is that of the client application
483       (i.e. the shell).
484

ENVIRONMENT

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
491       HOME
492           Used to determine the location of the configuration file, see
493           foot.ini(5) for details.
494
495       XDG_CONFIG_HOME
496           Used to determine the location of the configuration file, see
497           foot.ini(5) for details.
498
499       XDG_CONFIG_DIRS
500           Used to determine the location of the configuration file, see
501           foot.ini(5) for details.
502
503       XDG_RUNTIME_DIR
504           Used to construct the default PATH for the --server option, when no
505           explicit argument is given (see above).
506
507       WAYLAND_DISPLAY
508           Used to construct the default PATH for the --server option, when no
509           explicit argument is given (see above).
510
511       XCURSOR_THEME
512           The name of the Xcursor(3) theme to use for pointers (typically set
513           by the Wayland compositor).
514
515       XCURSOR_SIZE
516           The size to use for Xcursor(3) pointers (typically set by the Way‐
517           land compositor).
518
519   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
526       PWD
527           Current working directory (at the time of launching foot)
528
529       COLORTERM
530           This variable is set to truecolor, to indicate to client applica‐
531           tions that 24-bit RGB colors are supported.
532
533       In addition to the variables listed above, custom environment variables
534       may be defined in foot.ini(5).
535

BUGS

537       Please report bugs to https://codeberg.org/dnkl/foot/issues
538
539       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
543       The report should contain the following:
544
545       •   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
552

IRC

554       #foot on irc.libera.chat
555

SEE ALSO

557       foot.ini(5), footclient(1)
558
559
560
561                                  2023-10-14                           foot(1)
Impressum