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 SCROLLBACK SEARCH
202 ctrl+r
203 Search backward for the next match. If the search string is empty,
204 the last searched-for string is used.
205 ctrl+s
207 Search forward for the next match. If the search string is empty,
208 the last searched-for string is used.
209 ctrl+w
211 Extend current selection (and thus the search criteria) to the end
212 of the word, or the next word if currently at a word separating
213 character.
214 ctrl+shift+w
216 Same as ctrl+w, except that the only word separating characters are
217 whitespace characters.
218 ctrl+v, ctrl+shift+v, ctrl+y, XF86Paste
220 Paste from clipboard into the search buffer.
221 shift+insert
223 Paste from primary selection into the search buffer.
224 escape, ctrl+g, ctrl+c
226 Cancel the search
227 return
229 Finish the search and copy the current match to the primary selec‐
230 tion. The terminal selection is kept, allowing you to press
231 ctrl+shift+c to copy it to the clipboard.
232 URL MODE
234 t
235 Toggle URL visibility in jump label.
236 escape, ctrl+g, ctrl+c, ctrl+d
238 Exit URL mode without launching a URL.
239 MOUSE SHORTCUTS
241 left, single-click
242 Drag to select; when released, the selected text is copied to the
243 primary selection. This feature is normally disabled whenever the
244 client has enabled mouse tracking, but can be forced by holding
245 shift.
246 Holding ctrl will create a block selection.
248 left, double-click
250 Selects the word (separated by spaces, period, comma, parenthesis
251 etc) under the pointer. Hold ctrl to select everything under the
252 pointer up to, and until, the next space characters.
253 left, triple-click
255 Selects the entire row
256 middle
258 Paste from the primary selection
259 right
261 Extend current selection. Clicking immediately extends the selec‐
262 tion, while hold-and-drag allows you to interactively resize the
263 selection.
264 wheel
266 Scroll up/down in history
267
269 The font is specified in FontConfig syntax. That is, a colon-separated
270 list of font name and font options.
271 Examples:
273 • Dina:weight=bold:slant=italic
274 • Courier New:size=12
275
278 Foot supports URL detection. But, unlike many other terminal emulators,
279 where URLs are highlighted when they are hovered and opened by clicking
280 on them, foot uses a keyboard driven approach.
281 Pressing ctrl+shift+u enters “URL mode”, where all currently visible
283 URLs are underlined, and is associated with a “jump-label”. The jump-
284 label indicates the key sequence (e.g. ”AF”) to use to activate the
285 URL.
286 The key binding can, of course, be customized, like all other key bind‐
288 ings in foot. See show-urls-launch and show-urls-copy in foot.ini(5).
289 show-urls-launch by default opens the URL with xdg-open. This can be
291 changed with the url-launch option.
292 show-urls-copy is an alternative to show-urls-launch, that changes what
294 activating a URL does; instead of opening it, it copies it to the clip‐
295 board. It is unbound by default.
296 Jump label colors, the URL underline color, and the letters used in the
298 jump label key sequences can be configured.
299
301 By default, foot prefixes meta characters with ESC. This corresponds to
302 XTerm's metaSendsEscape option set to true.
303 This can be disabled programmatically with E[?1036l (and enabled again
305 with E[?1036h).
306 When disabled, foot will instead set the 8:th bit of meta character and
308 then UTF-8 encode it. This corresponds to XTerm's eightBitMeta option
309 set to true.
310 This can also be disabled programmatically with rmm (Reset Meta Mode,
312 E[?1034l), and enabled again with smm (Set Meta Mode, E[?1034h).
313
315 Foot transmits DEL (^?) on backspace. This corresponds to XTerm's
316 backarrowKey option set to false, and to DECBKM being reset.
317 To instead transmit BS (^H), press ctrl+backspace.
319 Note that foot does not implement DECBKM, and that the behavior de‐
321 scribed above cannot be changed.
322 Finally, pressing alt will prefix the transmitted byte with ESC.
324
326 By default, Num Lock overrides the run-time configuration keypad mode;
327 when active, the keypad is always considered to be in numerical mode.
328 This corresponds to XTerm's numLock option set to true.
329 In this mode, the keypad keys always sends either numbers (Num Lock is
331 active) or cursor movement keys (up, down, left, right, page up, page
332 down etc).
333 This can be disabled programmatically with E[?1035l (and enabled again
335 with E[?1035h).
336 When disabled, the keypad sends custom escape sequences instead of num‐
338 bers, when in application mode.
339
341 foot will search for a configuration file in the following locations,
342 in this order:
343 • XDG_CONFIG_HOME/foot/foot.ini (defaulting to ~/.con‐
345 fig/foot/foot.ini if unset)
346 • XDG_CONFIG_DIRS/foot/foot.ini (defaulting to
347 /etc/xdg/foot/foot.ini if unset)
348 An example configuration file containing all options with their default
351 value commented out will usually be installed to
352 /etc/xdg/foot/foot.ini.
353 For more information, see foot.ini(5).
355
357 Client applications use the terminfo identifier specified by the envi‐
358 ronment variable TERM (set by foot) to determine terminal capabilities.
359 Foot has two terminfo definitions: foot and foot-direct, with foot be‐
361 ing the default.
362 The difference between the two is in the number of colors they de‐
364 scribe; foot describes 256 colors and foot-direct 16.7 million colors
365 (24-bit truecolor).
366 Note that using the foot terminfo does not limit the number of usable
368 colors to 256; applications can still use 24-bit RGB colors. In fact,
369 most applications work best with foot (including 24-bit colors). Using
370 *-direct terminfo entries has been known to crash some ncurses applica‐
371 tions even.
372 There are however applications that need a *-direct terminfo entry for
374 24-bit support. Emacs is one such example.
375 While using either foot or foot-direct is strongly recommended, it is
377 possible to use e.g. xterm-256color as well. This can be useful when
378 remoting to a system where foot's terminfo entries cannot easily be in‐
379 stalled.
380 Note that terminfo entries can be installed in the user's home direc‐
382 tory. I.e. if you do not have root access, or if there is no distro
383 package for foot's terminfo entries, you can install foot's terminfo
384 entries manually, by copying foot and foot-direct to ~/.terminfo/f/.
385
387 XTGETTCAP is an escape sequence initially introduced by XTerm, and also
388 implemented (and extended, to some degree) by Kitty.
389 It allows querying the terminal for terminfo classic, file-based, ter‐
391 minfo definition. For example, if all applications used this feature,
392 you would no longer have to install foot’s terminfo on remote hosts you
393 SSH into.
394 XTerm’s implementation (as of XTerm-370) only supports querying key (as
396 in keyboard keys) capabilities, and three custom capabilities:
397 • TN - terminal name
399 • Co - number of colors (alias for the colors capability)
400 • RGB - number of bits per color channel (different semantics from
401 the RGB capability in file-based terminfo definitions!).
402 Kitty has extended this, and also supports querying all integer and
405 string capabilities.
406 Foot supports this, and extends it even further, to also include bool‐
408 ean capabilities. This means foot’s entire terminfo can be queried via
409 XTGETTCAP.
410 Note that both Kitty and foot handles responses to multi-capability
412 queries slightly differently, compared to XTerm.
413 XTerm will send a single DCS reply, with ;-separated capability/value
415 pairs. There are a couple of issues with this:
416 • The success/fail flag in the beginning of the response is always 1
418 (success), unless the very first queried capability is invalid.
419 • XTerm will not respond at all to an invalid capability, unless it’s
420 the first one in the XTGETTCAP query.
421 • XTerm will end the response at the first invalid capability.
422 In other words, if you send a large multi-capability query, you will
425 only get responses up to, but not including, the first invalid capabil‐
426 ity. All subsequent capabilities will be dropped.
427 Kitty and foot on the other hand, send one DCS response for each capa‐
429 bility in the multi query. This allows us to send a proper success/fail
430 flag for each queried capability. Responses for all queried capabili‐
431 ties are always sent. No queries are ever dropped.
432
434 Foot will exit with code 230 if there is a failure in foot itself.
435 In all other cases, the exit code is that of the client application
437 (i.e. the shell).
438
440 The following environment variables are used by foot:
441 SHELL
443 The default child process to run, when no command argument is spec‐
444 ified and the shell option in foot.ini(5) is not set.
445 XDG_CONFIG_HOME
447 Used to determine the location of the configuration file, see
448 foot.ini(5) for details.
449 XDG_CONFIG_DIRS
451 Used to determine the location of the configuration file, see
452 foot.ini(5) for details.
453 XDG_RUNTIME_DIR
455 Used to construct the default PATH for the --server option, when no
456 explicit argument is given (see above).
457 WAYLAND_DISPLAY
459 Used to construct the default PATH for the --server option, when no
460 explicit argument is given (see above).
461 XCURSOR_THEME
463 The name of the Xcursor(3) theme to use for pointers (typically set
464 by the Wayland compositor).
465 XCURSOR_SIZE
467 The size to use for Xcursor(3) pointers (typically set by the Way‐
468 land compositor).
469 The following environment variables are set in the child process:
471 TERM
473 terminfo/termcap identifier. This is used by client applications to
474 determine which capabilities a terminal supports. The value is set
475 according to either the --term command-line option or the term con‐
476 fig option in foot.ini(5).
477 COLORTERM
479 This variable is set to truecolor, to indicate to client applica‐
480 tions that 24-bit RGB colors are supported.
481
483 Please report bugs to https://codeberg.org/dnkl/foot/issues
484 Before you open a new issue, please search existing bug reports, both
486 open and closed ones. Chances are someone else has already reported the
487 same issue.
488 The report should contain the following:
490 • Foot version (foot --version).
492 • Log output from foot (start foot from another terminal).
493 • Which Wayland compositor (and version) you are running.
494 • If reporting a crash, please try to provide a bt full backtrace
495 with symbols.
496 • Steps to reproduce. The more details the better.
497
500 #foot on irc.libera.chat
501
503 foot.ini(5), footclient(1)
504 2022-04-28 foot(1)