The tmux server manages clients, sessions, windows and panes.
Clients are attached to sessions to interact with them, either when
they are created with the new-session command, or later with the
attach-session command. Each session has one or more windows
linked into it. Windows may be linked to multiple sessions and are
made up of one or more panes, each of which contains a pseudo
terminal. Commands for creating, linking and otherwise
manipulating windows are covered in the WINDOWS AND PANES section.
The following commands are available to manage clients and
sessions:
attach-session [-dErx] [-c working-directory] [-f flags] [-t
target-session]
(alias: attach)
If run from outside tmux, create a new client in the
current terminal and attach it to target-session. If used
from inside, switch the current client. If -d is
specified, any other clients attached to the session are
detached. If -x is given, send SIGHUP to the parent
process of the client as well as detaching the client,
typically causing it to exit. -f sets a comma-separated
list of client flags. The flags are:
active-pane
the client has an independent active pane
ignore-size
the client does not affect the size of other
clients
no-output
the client does not receive pane output in control
mode
pause-after=seconds
output is paused once the pane is seconds behind in
control mode
read-only
the client is read-only
wait-exit
wait for an empty line input before exiting in
control mode
A leading '!' turns a flag off if the client is already
attached. -r is an alias for -f read-only,ignore-size.
When a client is read-only, only keys bound to the
detach-client or switch-client commands have any effect. A
client with the active-pane flag allows the active pane to
be selected independently of the window's active pane used
by clients without the flag. This only affects the cursor
position and commands issued from the client; other
features such as hooks and styles continue to use the
window's active pane.
If no server is started, attach-session will attempt to
start it; this will fail unless sessions are created in the
configuration file.
The target-session rules for attach-session are slightly
adjusted: if tmux needs to select the most recently used
session, it will prefer the most recently used unattached
session.
-c will set the session working directory (used for new
windows) to working-directory.
If -E is used, the update-environment option will not be
applied.
detach-client [-aP] [-E shell-command] [-s target-session] [-t
target-client]
(alias: detach)
Detach the current client if bound to a key, the client
specified with -t, or all clients currently attached to the
session specified by -s. The -a option kills all but the
client given with -t. If -P is given, send SIGHUP to the
parent process of the client, typically causing it to exit.
With -E, run shell-command to replace the client.
has-session [-t target-session]
(alias: has)
Report an error and exit with 1 if the specified session
does not exist. If it does exist, exit with 0.
kill-server
Kill the tmux server and clients and destroy all sessions.
kill-session [-aC] [-t target-session]
Destroy the given session, closing any windows linked to it
and no other sessions, and detaching all clients attached
to it. If -a is given, all sessions but the specified one
is killed. The -C flag clears alerts (bell, activity, or
silence) in all windows linked to the session.
list-clients [-F format] [-t target-session]
(alias: lsc)
List all clients attached to the server. For the meaning
of the -F flag, see the FORMATS section. If target-session
is specified, list only clients connected to that session.
list-commands [-F format] [command]
(alias: lscm)
List the syntax of command or - if omitted - of all
commands supported by tmux.
list-sessions [-F format] [-f filter]
(alias: ls)
List all sessions managed by the server. -F specifies the
format of each line and -f a filter. Only sessions for
which the filter is true are shown. See the FORMATS
section.
lock-client [-t target-client]
(alias: lockc)
Lock target-client, see the lock-server command.
lock-session [-t target-session]
(alias: locks)
Lock all clients attached to target-session.
new-session [-AdDEPX] [-c start-directory] [-e environment] [-f
flags] [-F format] [-n window-name] [-s session-name] [-t
group-name] [-x width] [-y height] [shell-command]
(alias: new)
Create a new session with name session-name.
The new session is attached to the current terminal unless
-d is given. window-name and shell-command are the name of
and shell command to execute in the initial window. With
-d, the initial size comes from the global default-size
option; -x and -y can be used to specify a different size.
'-' uses the size of the current client if any. If -x or
-y is given, the default-size option is set for the
session. -f sets a comma-separated list of client flags
(see attach-session).
If run from a terminal, any termios(4) special characters
are saved and used for new windows in the new session.
The -A flag makes new-session behave like attach-session if
session-name already exists; in this case, -D behaves like
-d to attach-session, and -X behaves like -x to
attach-session.
If -t is given, it specifies a session group. Sessions in
the same group share the same set of windows - new windows
are linked to all sessions in the group and any windows
closed removed from all sessions. The current and previous
window and any session options remain independent and any
session in a group may be killed without affecting the
others. The group-name argument may be:
1. the name of an existing group, in which case the
new session is added to that group;
2. the name of an existing session - the new session
is added to the same group as that session,
creating a new group if necessary;
3. the name for a new group containing only the new
session.
-n and shell-command are invalid if -t is used.
The -P option prints information about the new session
after it has been created. By default, it uses the format
'#{session_name}:' but a different format may be specified
with -F.
If -E is used, the update-environment option will not be
applied. -e takes the form 'VARIABLE=value' and sets an
environment variable for the newly created session; it may
be specified multiple times.
refresh-client [-cDlLRSU] [-A pane:state] [-B name:what:format] [-C
XxY] [-f flags] [-t target-client] [adjustment]
(alias: refresh)
Refresh the current client if bound to a key, or a single
client if one is given with -t. If -S is specified, only
update the client's status line.
The -U, -D, -L -R, and -c flags allow the visible portion
of a window which is larger than the client to be changed.
-U moves the visible part up by adjustment rows and -D
down, -L left by adjustment columns and -R right. -c
returns to tracking the cursor automatically. If
adjustment is omitted, 1 is used. Note that the visible
position is a property of the client not of the window,
changing the current window in the attached session will
reset it.
-C sets the width and height of a control mode client. -A
allows a control mode client to trigger actions on a pane.
The argument is a pane ID (with leading '%'), a colon, then
one of 'on', 'off', 'continue' or 'pause'. If 'off', tmux
will not send output from the pane to the client and if all
clients have turned the pane off, will stop reading from
the pane. If 'continue', tmux will return to sending
output to the pane if it was paused (manually or with the
pause-after flag). If 'pause', tmux will pause the pane.
-A may be given multiple times for different panes.
-B sets a subscription to a format for a control mode
client. The argument is split into three items by colons:
name is a name for the subscription; what is a type of item
to subscribe to; format is the format. After a
subscription is added, changes to the format are reported
with the %subscription-changed notification, at most once a
second. If only the name is given, the subscription is
removed. what may be empty to check the format only for
the attached session, or one of: a pane ID such as '%0';
'%*' for all panes in the attached session; a window ID
such as '@0'; or '@*' for all windows in the attached
session.
-f sets a comma-separated list of client flags, see
attach-session.
-l requests the clipboard from the client using the
xterm(1) escape sequence and stores it in a new paste
buffer.
-L, -R, -U and -D move the visible portion of the window
left, right, up or down by adjustment, if the window is
larger than the client. -c resets so that the position
follows the cursor. See the window-size option.
rename-session [-t target-session] new-name
(alias: rename)
Rename the session to new-name.
show-messages [-JT] [-t target-client]
(alias: showmsgs)
Show server messages or information. Messages are stored,
up to a maximum of the limit set by the message-limit
server option. -J and -T show debugging information about
jobs and terminals.
source-file [-Fnqv] path ...
(alias: source)
Execute commands from one or more files specified by path
(which may be glob(7) patterns). If -F is present, then
path is expanded as a format. If -q is given, no error
will be returned if path does not exist. With -n, the file
is parsed but no commands are executed. -v shows the
parsed commands and line numbers if possible.
start-server
(alias: start)
Start the tmux server, if not already running, without
creating any sessions.
Note that as by default the tmux server will exit with no
sessions, this is only useful if a session is created in
~/.tmux.conf, exit-empty is turned off, or another command
is run as part of the same command sequence. For example:
$ tmux start \; show -g
suspend-client [-t target-client]
(alias: suspendc)
Suspend a client by sending SIGTSTP (tty stop).
switch-client [-ElnprZ] [-c target-client] [-t target-session] [-T
key-table]
(alias: switchc)
Switch the current session for client target-client to
target-session. As a special case, -t may refer to a pane
(a target that contains ':', '.' or '%'), to change
session, window and pane. In that case, -Z keeps the
window zoomed if it was zoomed. If -l, -n or -p is used,
the client is moved to the last, next or previous session
respectively. -r toggles the client read-only and
ignore-size flags (see the attach-session command).
If -E is used, update-environment option will not be
applied.
-T sets the client's key table; the next key from the
client will be interpreted from key-table. This may be
used to configure multiple prefix keys, or to bind commands
to sequences of keys. For example, to make typing 'abc'
run the list-keys command:
bind-key -Ttable2 c list-keys
bind-key -Ttable1 b switch-client -Ttable2
bind-key -Troot a switch-client -Ttable1
