.\" Generated by scdoc 1.11.5
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "footclient" "1" "2026\-09\-03"
.PP
.SH NAME
footclient \- start new terminals in a foot server
.PP
.SH SYNOPSIS
\fBfootclient\fR [\fIOPTIONS\fR]
.br
\fBfootclient\fR [\fIOPTIONS\fR] <\fIcommand\fR> [\fICOMMAND OPTIONS\fR]
.PP
All trailing (non\-option) arguments are treated as a command, and its
arguments, to execute (instead of the default shell).\&
.PP
.SH DESCRIPTION
.PP
\fBfootclient\fR is used together with \fBfoot\fR(1) in \fB\-\-server\fR
mode.\&
.PP
Running it without arguments will open a new terminal window (hosted
in the foot server), with your default shell.\& The exit code will be
that of the terminal.\& I.\&e \fBfootclient\fR does not exit until the
terminal has terminated.\&
.PP
.SH OPTIONS
.PP
\fB\-t\fR,\fB\-\-term\fR=\fITERM\fR
.RS 4
Value to set the environment variable \fBTERM\fR to (see \fBTERMINFO\fR
and \fBENVIRONMENT\fR).\& Default: \fIfoot\fR.\&
.PP
.RE
\fB\-T\fR,\fB\-\-title\fR=\fITITLE\fR
.RS 4
Initial window title.\& Default: \fIfoot\fR.\&
.PP
.RE
\fB\-a\fR,\fB\-\-app\-id\fR=\fIID\fR
.RS 4
Value to set the \fBapp\-id\fR property on the Wayland window
to.\& Default: \fIfoot\fR (normal mode), or \fIfootclient\fR (server mode).\&
.PP
.RE
\fB\-\-class\fR=\fIID\fR
.RS 4
Alias for \fB\-\-app\-id\fR.\&
.PP
.RE
\fBtoplevel\-tag\fR=\fITAG\fR
.RS 4
Value to set the \fBtoplevel\-tag\fR property on the Wayland window
to.\& The compositor can use this value for session management,
window rules etc.\& Default: \fInot set\fR
.PP
.RE
\fB\-w\fR,\fB\-\-window\-size\-pixels\fR=\fIWIDTHxHEIGHT\fR
.RS 4
Set initial window width and height, in pixels.\& Default: \fI700x500\fR.\&
.PP
.RE
\fB\-W\fR,\fB\-\-window\-size\-chars\fR=\fIWIDTHxHEIGHT\fR
.RS 4
Set initial window width and height, in characters.\& Default: \fInot set\fR.\&
.PP
.RE
\fB\-m\fR,\fB\-\-maximized\fR
.RS 4
Start in maximized mode.\& If both \fB\-\-maximized\fR and \fB\-\-fullscreen\fR
are specified, the \fIlast\fR one takes precedence.\&
.PP
.RE
\fB\-F\fR,\fB\-\-fullscreen\fR
.RS 4
Start in fullscreen mode.\& If both \fB\-\-maximized\fR and \fB\-\-fullscreen\fR
are specified, the \fIlast\fR one takes precedence.\&
.PP
.RE
\fB\-L\fR,\fB\-\-login\-shell\fR
.RS 4
Start a login shell, by prepending a '\&\-'\& to argv[0].\&
.PP
.RE
\fB\-D\fR,\fB\-\-working\-directory\fR=\fIDIR\fR
.RS 4
Initial working directory for the client application.\& Default:
\fICWD of footclient\fR.\&
.PP
.RE
\fB\-s\fR,\fB\-\-server\-socket\fR=\fIPATH\fR
.RS 4
Connect to \fIPATH\fR instead of
\fB$XDG_RUNTIME_DIR/foot\-$WAYLAND_DISPLAY.\&sock\fR.\&
.PP
.RE
\fB\-H\fR,\fB\-\-hold\fR
.RS 4
Remain open after child process exits.\&
.PP
.RE
\fB\-N\fR,\fB\-\-no\-wait\fR
.RS 4
Detach the client process from the running terminal, exiting
immediately.\&
.PP
.RE
\fB\-o\fR,\fB\-\-override\fR=[\fISECTION\fR.\&]\fIKEY\fR=\fIVALUE\fR
.RS 4
Override an option set in the configuration file.\& If \fISECTION\fR is not
given, defaults to \fImain\fR.\&
.PP
.RE
\fB\-E\fR,\fB\-\-client\-environment\fR
.RS 4
The child process in the new terminal instance will use
footclient'\&s environment, instead of the server'\&s.\&
.PP
Environment variables listed in the \fBVariables set in the child
process\fR section will be overwritten by the foot server.\& For
example, the new terminal will use \fBTERM\fR from the configuration,
not footclient'\&s environment.\&
.PP
.RE
\fB\-d\fR,\fB\-\-log\-level\fR={\fBinfo\fR,\fBwarning\fR,\fBerror\fR,\fBnone\fR}
.RS 4
Log level, used both for log output on stderr as well as
syslog.\& Default: \fIwarning\fR.\&
.PP
.RE
\fB\-l\fR,\fB\-\-log\-colorize\fR=[{\fBnever\fR,\fBalways\fR,\fBauto\fR}]
.RS 4
Enables or disables colorization of log output on stderr.\&
.PP
.RE
\fB\-v\fR,\fB\-\-version\fR
.RS 4
Show the version number and quit
.PP
.RE
\fB\-e\fR
.RS 4
Ignored; for compatibility with \fBxterm \-e\fR.\& See \fBfoot\fR(1) for more
details.\&
.PP
.RE
.SH EXIT STATUS
.PP
Footclient will exit with code 220 if there is a failure in footclient
itself (for example, the server socket does not exist).\&
.PP
If \fB\-N\fR,\fB\-\-no\-wait\fR is used, footclient exits with code 0 as soon as
the foot server has been instructed to open a new window.\&
.PP
If not, footclient may also exit with code 230.\& This indicates a
failure in the foot server.\&
.PP
In all other cases the exit code is that of the client application
(i.\&e.\& the shell).\&
.PP
.SH TERMINFO
.PP
Client applications use the terminfo identifier specified by the
environment variable \fBTERM\fR (set by foot) to determine terminal
capabilities.\&
.PP
Foot has two terminfo definitions: \fBfoot\fR and \fBfoot\-direct\fR, with
\fBfoot\fR being the default.\&
.PP
The difference between the two is in the number of colors they
describe; \fBfoot\fR describes 256 colors and \fBfoot\-direct\fR 16.\&7 million
colors (24\-bit truecolor).\&
.PP
Note that using the \fBfoot\fR terminfo does not limit the number of
usable colors to 256; applications can still use 24\-bit RGB colors.\& In
fact, most applications work best with \fBfoot\fR (including 24\-bit
colors)).\& Using \fB*\-direct\fR terminfo entries has been known to crash
some ncurses applications even.\&
.PP
There are however applications that need a \fB*\-direct\fR terminfo entry
for 24\-bit support.\& Emacs is one such example.\&
.PP
While using either \fBfoot\fR or \fBfoot\-direct\fR is strongly recommended, it
is possible to use e.\&g.\& \fBxterm\-256color\fR as well.\& This can be useful
when remoting to a system where foot'\&s terminfo entries cannot easily
be installed.\&
.PP
Note that terminfo entries can be installed in the user'\&s home
directory.\& I.\&e.\& if you do not have root access, or if there is no
distro package for foot'\&s terminfo entries, you can install foot'\&s
terminfo entries manually, by copying \fBfoot\fR and \fBfoot\-direct\fR to
\fB\(ti/.\&terminfo/f/\fR.\&
.PP
.SH ENVIRONMENT
.PP
.SS Variables used by footclient
.PP
\fBXDG_RUNTIME_DIR\fR
.RS 4
Used to construct the default \fIPATH\fR for the \fB\-\-server\-socket\fR
option, when no explicit argument is given (see above).\&
.PP
.RE
\fBWAYLAND_DISPLAY\fR
.RS 4
Used to construct the default \fIPATH\fR for the \fB\-\-server\-socket\fR
option, when no explicit argument is given (see above).\&
.PP
.RE
If the socket at default \fIPATH\fR does not exist, \fBfootclient\fR will
fallback to the less specific path, with the following priority:
\fB$XDG_RUNTIME_DIR/foot\-$WAYLAND_DISPLAY.\&sock\fR,
\fB$XDG_RUNTIME_DIR/foot.\&sock\fR, \fB/tmp/foot.\&sock\fR.\&
.PP
.SS Variables set in the child process
.PP
\fBTERM\fR
.RS 4
terminfo/termcap identifier.\& This is used by client applications
to determine which capabilities a terminal supports.\& The value is
set according to either the \fB\-\-term\fR command\-line option or the
\fBterm\fR config option in \fBfoot.\&ini\fR(5).\&
.PP
.RE
\fBCOLORTERM\fR
.RS 4
This variable is set to \fBtruecolor\fR, to indicate to client
applications that 24\-bit RGB colors are supported.\&
.PP
.RE
\fBPWD\fR
.RS 4
Current working directory (at the time of launching foot)
.PP
.RE
\fBSHELL\fR
.RS 4
Set to the launched shell, if the shell is valid (it is listed in
\fB/etc/shells\fR).\&
.PP
.RE
In addition to the variables listed above, custom environment
variables may be defined in \fBfoot.\&ini\fR(5).\&
.PP
.SS Variables *unset* in the child process
.PP
\fBTERM_PROGRAM\fR
\fBTERM_PROGRAM_VERSION\fR
.RS 4
These environment variables are set by certain other terminal
emulators.\& We unset them, to prevent applications from
misdetecting foot.\&
.PP
.RE
In addition to the variables listed above, custom environment
variables to unset may be defined in \fBfoot.\&ini\fR(5).\&
.PP
.SH Signals
.PP
The following signals have special meaning in footclient:
.PP
.PD 0
.IP \(bu 4
SIGUSR1: switch to the dark color theme (\fB[colors\-dark]\fR).\&
.IP \(bu 4
SIGUSR2: switch to the light color theme (\fB[colors\-light]\fR).\&
.PD
.PP
When sending SIGUSR1/SIGUSR2 to a footclient instance, the theme is
changed in that instance only.\& This is different from when you send
SIGUSR1/SIGUSR2 to the server process, where all instances change the
theme.\&
.PP
Note: for obvious reasons, this is not supported when footclient is
started with \fB\-\-no\-wait\fR.\&
.PP
.SH SEE ALSO
.PP
\fBfoot\fR(1)