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. Default: $XDG_CON‐
27           FIG_HOME/foot/foot.ini.
28
29       -C,--check-config
30           Verify configuration and then exit with 0 if ok, otherwise exit
31           with 230 (see EXIT STATUS).
32
33       -o,--override=[SECTION.]KEY=VALUE
34           Override an option set in the configuration file. If SECTION is not
35           given, defaults to main.
36
37       -f,--font=FONT
38           Comma separated list of fonts to use, in fontconfig format (see
39           FONT FORMAT).
40
41           The first font is the primary font. The remaining fonts are fall‐
42           back fonts that will be used whenever a glyph cannot be found in
43           the primary font.
44
45           The fallback fonts are searched in the order they appear. If a
46           glyph cannot be found in any of the fallback fonts, the dynamic
47           fallback list from fontconfig (for the primary font) is searched.
48
49           Default: monospace.
50
51       -w,--window-size-pixels=WIDTHxHEIGHT
52           Set initial window width and height, in pixels. Default: 700x500.
53
54       -W,--window-size-chars=WIDTHxHEIGHT
55           Set initial window width and height, in characters. Default: not
56           set.
57
58       -t,--term=TERM
59           Value to set the environment variable TERM to (see TERMINFO and EN‐
60           VIRONMENT). Default: foot.
61
62       -T,--title=TITLE
63           Initial window title. Default: foot.
64
65       -a,--app-id=ID
66           Value to set the app-id property on the Wayland window to. Default:
67           foot.
68
69       -m,--maximized
70           Start in maximized mode. If both --maximized and --fullscreen are
71           specified, the last one takes precedence.
72
73       -F,--fullscreen
74           Start in fullscreen mode. If both --maximized and --fullscreen are
75           specified, the last one takes precedence.
76
77       -L,--login-shell
78           Start a login shell, by prepending a '-' to argv[0].
79
80       -D,--working-directory=DIR
81           Initial working directory for the client application. Default: CWD
82           of foot.
83
84       -s,--server[=PATH]
85           Run as a server. In this mode, a single foot instance hosts multi‐
86           ple terminals (windows). Use footclient(1) to launch new terminals.
87
88           This saves some memory since for example fonts and glyph caches can
89           be shared between the terminals.
90
91           It also saves upstart time since the config has already been loaded
92           and parsed, and most importantly, fonts have already been loaded
93           (and their glyph caches are likely to already have been populated).
94
95           Each terminal will have its own rendering threads, but all Wayland
96           communication, as well as input/output to the shell, is multiplexed
97           in the main thread. Thus, this mode might result in slightly worse
98           performance when multiple terminals are under heavy load.
99
100           Also be aware that should one terminal crash, it will take all the
101           others with it.
102
103           The default path is $XDG_RUNTIME_DIR/foot-$WAYLAND_DISPLAY.sock.
104
105           If $XDG_RUNTIME_DIR is not set, the default path is instead
106           /tmp/foot.sock.
107
108           If $XDG_RUNTIME_DIR is set, but $WAYLAND_DISPLAY is not, the de‐
109           fault path is $XDG_RUNTIME_DIR/foot.sock.
110
111           Note that if you change the default, you will also need to use the
112           --server-socket option in footclient(1) and point it to your custom
113           socket path.
114
115       -H,--hold
116           Remain open after child process exits.
117
118       -p,--print-pid=FILE|FD
119           Print PID to this file, or FD, when successfully started. The file
120           (or FD) is closed immediately after writing the PID. When a FILE as
121           been specified, the file is unlinked at exit.
122
123           This option can only be used in combination with -s,--server.
124
125       -d,--log-level={info,warning,error,none}
126           Log level, used both for log output on stderr as well as syslog.
127           Default: info.
128
129       -l,--log-colorize=[{never,always,auto}]
130           Enables or disables colorization of log output on stderr. Default:
131           auto.
132
133       -S,--log-no-syslog
134           Disables syslog logging. Logging is only done on stderr. This op‐
135           tion can only be used in combination with -s,--server.
136
137       -v,--version
138           Show the version number and quit.
139
140       -e
141           Ignored; for compatibility with xterm -e.
142
143           This option was added in response to several program launchers
144           passing -e to arbitrary terminals, under the assumption that they
145           all implement the same semantics for it as xterm(1). Ignoring it
146           allows foot to be invoked as e.g. foot -e man foot with the same
147           results as with xterm, instead of producing an "invalid option" er‐
148           ror.
149

EXIT STATUS

151       Foot will exit with code 230 if there is a failure in foot itself.
152
153       In all other cases, the exit code is that of the client application
154       (i.e. the shell).
155

KEYBOARD SHORTCUTS

157       The following keyboard shortcuts are available.
158
159   NORMAL MODE
160       Note that these are just the defaults; they can be changed in
161       foot.ini(5).
162
163       shift+page up/page down
164           Scroll up/down in history
165
166       ctrl+shift+c
167           Copy selected text to the clipboard
168
169       ctrl+shift+v
170           Paste from clipboard
171
172       shift+insert
173           Paste from the primary selection.
174
175       ctrl+shift+r
176           Start a scrollback search
177
178       ctrl++, ctrl+=
179           Increase font size by 1pt
180
181       ctrl+-
182           Decrease font size by 1pt
183
184       ctrl+0
185           Reset font size
186
187       ctrl+shift+n
188           Spawn a new terminal. If the shell has been configured to emit the
189           OSC 7 escape sequence, the new terminal will start in the current
190           working directory.
191
192   SCROLLBACK SEARCH
193       ctrl+r
194           Search backward for the next match
195
196       ctrl+s
197           Search forward for the next match
198
199       ctrl+w
200           Extend current selection (and thus the search criteria) to the end
201           of the word, or the next word if currently at a word separating
202           character.
203
204       ctrl+shift+w
205           Same as ctrl+w, except that the only word separating characters are
206           whitespace characters.
207
208       ctrl+v, ctrl+y
209           Paste from clipboard into the search buffer.
210
211       shift+insert
212           Paste from primary selection into the search buffer.
213
214       escape, ctrl+g, ctrl+c
215           Cancel the search
216
217       return
218           Finish the search and copy the current match to the primary selec‐
219           tion. The terminal selection is kept, allowing you to press
220           ctrl+shift+c to copy it to the clipboard.
221

MOUSE SHORTCUTS

223       left, single-click
224           Drag to select; when released, the selected text is copied to the
225           primary selection. This feature is normally disabled whenever the
226           client has enabled mouse tracking, but can be forced by holding
227           shift.
228
229           Holding ctrl will create a block selection.
230
231       left, double-click
232           Selects the word (separated by spaces, period, comma, parenthesis
233           etc) under the pointer. Hold ctrl to select everything under the
234           pointer up to, and until, the next space characters.
235
236       left, triple-click
237           Selects the entire row
238
239       middle
240           Paste from the primary selection
241
242       right
243           Extend current selection. Clicking immediately extends the selec‐
244           tion, while hold-and-drag allows you to interactively resize the
245           selection.
246
247       wheel
248           Scroll up/down in history
249

FONT FORMAT

251       The font is specified in FontConfig syntax. That is, a colon-separated
252       list of font name and font options.
253
254       Examples:
255       •   Dina:weight=bold:slant=italic
256       •   Courier New:size=12
257
258

URLs

260       Foot supports URL detection. But, unlike many other terminal emulators,
261       where URLs are highlighted when they are hovered and opened by clicking
262       on them, foot uses a keyboard driven approach.
263
264       Pressing ctrl+shift+u enters “URL mode”, where all currently visible
265       URLs are underlined, and is associated with a “jump-label”. The jump-
266       label indicates the key sequence (e.g. ”AF”) to use to activate the
267       URL.
268
269       The key binding can, of course, be customized, like all other key bind‐
270       ings in foot. See show-urls-launch and show-urls-copy in foot.ini(5).
271
272       show-urls-launch by default opens the URL with xdg-open. This can be
273       changed with the url-launch option.
274
275       show-urls-copy is an alternative to show-urls-launch, that changes what
276       activating an URL does; instead of opening it, it copies it to the
277       clipboard. It is unbound by default.
278
279       Jump label colors, the URL underline color, and the letters used in the
280       jump label key sequences can be configured.
281

ALT/META CHARACTERS

283       By default, foot prefixes meta characters with ESC. This corresponds to
284       XTerm's metaSendsEscape option set to true.
285
286       This can be disabled programmatically with E[?1036l (and enabled again
287       with E[?1036h).
288
289       When disabled, foot will instead set the 8:th bit of meta character and
290       then UTF-8 encode it. This corresponds to XTerm's eightBitMeta option
291       set to true.
292
293       This can also be disabled programmatically with rmm (Reset Meta Mode,
294       E[?1034l), and enabled again with smm (Set Meta Mode, E[?1034h).
295

BACKSPACE

297       Foot transmits DEL (^?) on backspace. This corresponds to XTerm's
298       backarrowKey option set to false, and to DECBKM being reset.
299
300       To instead transmit BS (^H), press ctrl+backspace.
301
302       Note that foot does not implement DECBKM, and that the behavior de‐
303       scribed above cannot be changed.
304
305       Finally, pressing alt will prefix the transmitted byte with ESC.
306

KEYPAD

308       By default, Num Lock overrides the run-time configuration keypad mode;
309       when active, the keypad is always considered to be in numerical mode.
310       This corresponds to XTerm's numLock option set to true.
311
312       In this mode, the keypad keys always sends either numbers (Num Lock is
313       active) or cursor movement keys (up, down, left, right, page up, page
314       down etc).
315
316       This can be disabled programmatically with E[?1035l (and enabled again
317       with E[?1035h).
318
319       When disabled, the keypad sends custom escape sequences instead of num‐
320       bers, when in application mode.
321

CONFIGURATION

323       See foot.ini(5)
324

TERMINFO

326       Client applications use the terminfo identifier specified by the envi‐
327       ronment variable TERM (set by foot) to determine terminal capabilities.
328
329       Foot has two terminfo definitions: foot and foot-direct, with foot be‐
330       ing the default.
331
332       The difference between the two is in the number of colors they de‐
333       scribe; foot describes 256 colors and foot-direct 16.7 million colors
334       (24-bit truecolor).
335
336       Note that using the foot terminfo does not limit the number of usable
337       colors to 256; applications can still use 24-bit RGB colors. In fact,
338       most applications work best with foot (including 24-bit colors)). Using
339       *-direct terminfo entries has been known to crash some ncurses applica‐
340       tions even.
341
342       There are however applications that need a *-direct terminfo entry for
343       24-bit support. Emacs is one such example.
344
345       While using either foot or foot-direct is strongly recommended, it is
346       possible to use e.g. xterm-256color as well. This can be useful when
347       remoting to a system where foot's terminfo entries cannot easily be in‐
348       stalled.
349
350       Note that terminfo entries can be installed in the user's home direc‐
351       tory. I.e. if you do not have root access, or if there is no distro
352       package for foot's terminfo entries, you can install foot's terminfo
353       entries manually, by copying foot and foot-direct to ~/.terminfo/f/.
354

ENVIRONMENT

356       The following environment variables are used by foot:
357
358       SHELL
359           The default child process to run, when no command argument is spec‐
360           ified and the shell option in foot.ini(5) is not set.
361
362       XDG_CONFIG_HOME
363           Used to determine the default location of foot.ini(5).
364
365       XDG_CONFIG_DIRS
366           Used to determine the default fallback location of foot.ini(5),
367           when not found in ${XDG_CONFIG_HOME:-~/.config}.
368
369       XDG_RUNTIME_DIR
370           Used to construct the default PATH for the --server option, when no
371           explicit argument is given (see above).
372
373       WAYLAND_DISPLAY
374           Used to construct the default PATH for the --server option, when no
375           explicit argument is given (see above).
376
377       XCURSOR_THEME
378           The name of the Xcursor(3) theme to use for pointers (typically set
379           by the Wayland compositor).
380
381       XCURSOR_SIZE
382           The size to use for Xcursor(3) pointers (typically set by the Way‐
383           land compositor).
384
385       The following environment variables are set in the child process:
386
387       TERM
388           terminfo/termcap identifier. This is used by client applications to
389           determine which capabilities a terminal supports. The value is set
390           according to either the --term command-line option or the term con‐
391           fig option in foot.ini(5).
392
393       COLORTERM
394           This variable is set to truecolor, to indicate to client applica‐
395           tions that 24-bit RGB colors are supported.
396

BUGS

398       Please report bugs to https://codeberg.org/dnkl/foot/issues
399
400       Before you open a new issue, please search existing bug reports, both
401       open and closed ones. Chances are someone else has already reported the
402       same issue.
403
404       The report should contain the following:
405
406       •   Foot version (foot --version).
407       •   Log output from foot (start foot from another terminal).
408       •   Which Wayland compositor (and version) you are running.
409       •   If reporting a crash, please try to provide a bt full backtrace
410           with symbols.
411       •   Steps to reproduce. The more details the better.
412
413

IRC

415       #foot on irc.libera.chat
416

SEE ALSO

418       foot.ini(5), footclient(1)
419
420
421
422                                  2021-11-22                           foot(1)
Impressum