1foot(1) General Commands Manual foot(1)
2
3
4
6 foot - Wayland terminal emulator
7
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
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
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
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
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
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
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
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
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
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
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
323 See foot.ini(5)
324
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
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
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
415 #foot on irc.libera.chat
416
418 foot.ini(5), footclient(1)
419
420
421
422 2021-11-22 foot(1)