home | help 
footclient(1)		     General Commands Manual		   footclient(1)

NAME
     footclient - start new terminals in a foot server

SYNOPSIS
     footclient [OPTIONS]
     footclient [OPTIONS] <command> [COMMAND OPTIONS]

     All trailing (non-option) arguments are treated as a command, and its argu-
     ments, to execute (instead of the default shell).

DESCRIPTION
     footclient is used together with foot(1) in --server mode.

     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 footclient does not exit until the terminal has terminated.

OPTIONS
     -t,--term=TERM
	 Value to set the environment variable TERM to (see TERMINFO  and  ENVI-
	 RONMENT). Default: foot.

     -T,--title=TITLE
	 Initial window title. Default: foot.

     -a,--app-id=ID
	 Value	to  set  the  app-id property on the Wayland window to. Default:
	 foot (normal mode), or footclient (server mode).

     toplevel-tag=TAG
	 Value to set the toplevel-tag property on the Wayland	window	to.  The
	 compositor can use this value for session management, window rules etc.
	 Default: not set

     -w,--window-size-pixels=WIDTHxHEIGHT
	 Set initial window width and height, in pixels. Default: 700x500.

     -W,--window-size-chars=WIDTHxHEIGHT
	 Set initial window width and height, in characters. Default: not set.

     -m,--maximized
	 Start in maximized mode. If both --maximized and --fullscreen are spec-
	 ified, the last one takes precedence.

     -F,--fullscreen
	 Start	in  fullscreen	mode.  If  both --maximized and --fullscreen are
	 specified, the last one takes precedence.

     -L,--login-shell
	 Start a login shell, by prepending a '-' to argv[0].

     -D,--working-directory=DIR
	 Initial working directory for the client application. Default:  CWD  of
	 footclient.

     -s,--server-socket=PATH
	 Connect to PATH instead of $XDG_RUNTIME_DIR/foot-$WAYLAND_DISPLAY.sock.

     -H,--hold
	 Remain open after child process exits.

     -N,--no-wait
	 Detach  the  client  process from the running terminal, exiting immedi-
	 ately.

     -o,--override=[SECTION.]KEY=VALUE
	 Override an option set in the configuration file.  If	SECTION  is  not
	 given, defaults to main.

     -E,--client-environment
	 The  child  process  in the new terminal instance will use footclient's
	 environment, instead of the server's.

	 Environment variables listed in the Variables set in the child  process
	 section  will	be  overwritten by the foot server. For example, the new
	 terminal will use TERM from the configuration, not  footclient's  envi-
	 ronment.

     -d,--log-level={info,warning,error,none}
	 Log  level,  used  both for log output on stderr as well as syslog. De-
	 fault: warning.

     -l,--log-colorize=[{never,always,auto}]
	 Enables or disables colorization of log output on stderr.

     -v,--version
	 Show the version number and quit

     -e
	 Ignored; for compatibility with xterm -e. See foot(1) for more details.

EXIT STATUS
     Footclient will exit with code 220 if there is a failure in footclient  it-
     self (for example, the server socket does not exist).

     If  -N,--no-wait  is used, footclient exits with code 0 as soon as the foot
     server has been instructed to open a new window.

     If not, footclient may also exit with code 230. This indicates a failure in
     the foot server.

     In all other cases the exit code is that of the  client  application  (i.e.
     the shell).

TERMINFO
     Client  applications  use the terminfo identifier specified by the environ-
     ment variable TERM (set by foot) to determine terminal capabilities.

     Foot has two terminfo definitions: foot and foot-direct,  with  foot  being
     the default.

     The  difference  between  the two is in the number of colors they describe;
     foot describes 256 colors and foot-direct 16.7 million colors (24-bit true-
     color).

     Note that using the foot terminfo does not limit the number of usable  col-
     ors to 256; applications can still use 24-bit RGB colors. In fact, most ap-
     plications  work  best with foot (including 24-bit colors)). Using *-direct
     terminfo entries has been known to crash some ncurses applications even.

     There are however applications that need  a  *-direct  terminfo  entry  for
     24-bit support. Emacs is one such example.

     While  using either foot or foot-direct is strongly recommended, it is pos-
     sible to use e.g. xterm-256color as well. This can be useful when	remoting
     to a system where foot's terminfo entries cannot easily be installed.

     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 foot and foot-direct to ~/.terminfo/f/.

ENVIRONMENT
   Variables used by footclient
     XDG_RUNTIME_DIR
	 Used to construct the default PATH for the --server-socket option, when
	 no explicit argument is given (see above).

     WAYLAND_DISPLAY
	 Used to construct the default PATH for the --server-socket option, when
	 no explicit argument is given (see above).

     If the socket at default PATH does not exist, footclient will  fallback  to
     the   less   specific   path,   with   the  following  priority:  $XDG_RUN-
     TIME_DIR/foot-$WAYLAND_DISPLAY.sock,	     $XDG_RUNTIME_DIR/foot.sock,
     /tmp/foot.sock.

   Variables set in the child process
     TERM
	 terminfo/termcap identifier. This is used by client applications to de-
	 termine  which  capabilities  a terminal supports. The value is set ac-
	 cording to either the --term command-line option or the term config op-
	 tion in foot.ini(5).

     COLORTERM
	 This variable is set to truecolor, to indicate to  client  applications
	 that 24-bit RGB colors are supported.

     PWD
	 Current working directory (at the time of launching foot)

     SHELL
	 Set  to  the  launched  shell,  if  the shell is valid (it is listed in
	 /etc/shells).

     In addition to the variables listed above, custom environment variables may
     be defined in foot.ini(5).

   Variables *unset* in the child process
     TERM_PROGRAM TERM_PROGRAM_VERSION
	 These environment variables are set by certain  other	terminal  emula-
	 tors. We unset them, to prevent applications from misdetecting foot.

     In  addition to the variables listed above, custom environment variables to
     unset may be defined in foot.ini(5).

Signals
     The following signals have special meaning in footclient:

     *	 SIGUSR1: switch to the dark color theme ([colors-dark]).
     *	 SIGUSR2: switch to the light color theme ([colors-light]).

     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.

     Note: for obvious reasons, this is not supported when footclient is started
     with --no-wait.

SEE ALSO
     foot(1)

				   2026-08-27			   footclient(1)
home | help