1TMUX(1) BSD General Commands Manual TMUX(1)
2
4 tmux — terminal multiplexer
5
7 tmux [-2CDluvV] [-c shell-command] [-f file] [-L socket-name]
8 [-S socket-path] [-T features] [command [flags]]
9
11 tmux is a terminal multiplexer: it enables a number of terminals to be
12 created, accessed, and controlled from a single screen. tmux may be de‐
13 tached from a screen and continue running in the background, then later
14 reattached.
15 When tmux is started it creates a new session with a single window and
17 displays it on screen. A status line at the bottom of the screen shows
18 information on the current session and is used to enter interactive com‐
19 mands.
20 A session is a single collection of pseudo terminals under the management
22 of tmux. Each session has one or more windows linked to it. A window
23 occupies the entire screen and may be split into rectangular panes, each
24 of which is a separate pseudo terminal (the pty(4) manual page documents
25 the technical details of pseudo terminals). Any number of tmux instances
26 may connect to the same session, and any number of windows may be present
27 in the same session. Once all sessions are killed, tmux exits.
28 Each session is persistent and will survive accidental disconnection
30 (such as ssh(1) connection timeout) or intentional detaching (with the
31 ‘C-b d’ key strokes). tmux may be reattached using:
32 $ tmux attach
34 In tmux, a session is displayed on screen by a client and all sessions
36 are managed by a single server. The server and each client are separate
37 processes which communicate through a socket in /tmp.
38 The options are as follows:
40 -2 Force tmux to assume the terminal supports 256 colours.
42 This is equivalent to -T 256.
43 -C Start in control mode (see the CONTROL MODE section).
45 Given twice (-CC) disables echo.
46 -c shell-command
48 Execute shell-command using the default shell. If neces‐
49 sary, the tmux server will be started to retrieve the
50 default-shell option. This option is for compatibility
51 with sh(1) when tmux is used as a login shell.
52 -D Do not start the tmux server as a daemon. This also turns
54 the exit-empty option off. With -D, command may not be
55 specified.
56 -f file Specify an alternative configuration file. By default,
58 tmux loads the system configuration file from
59 /etc/tmux.conf, if present, then looks for a user configu‐
60 ration file at ~/.tmux.conf.
61 The configuration file is a set of tmux commands which are
63 executed in sequence when the server is first started.
64 tmux loads configuration files once when the server process
65 has started. The source-file command may be used to load a
66 file later.
67 tmux shows any error messages from commands in configura‐
69 tion files in the first session created, and continues to
70 process the rest of the configuration file.
71 -L socket-name
73 tmux stores the server socket in a directory under
74 TMUX_TMPDIR or /tmp if it is unset. The default socket is
75 named default. This option allows a different socket name
76 to be specified, allowing several independent tmux servers
77 to be run. Unlike -S a full path is not necessary: the
78 sockets are all created in a directory tmux-UID under the
79 directory given by TMUX_TMPDIR or in /tmp. The tmux-UID
80 directory is created by tmux and must not be world read‐
81 able, writable or executable.
82 If the socket is accidentally removed, the SIGUSR1 signal
84 may be sent to the tmux server process to recreate it (note
85 that this will fail if any parent directories are missing).
86 -l Behave as a login shell. This flag currently has no effect
88 and is for compatibility with other shells when using tmux
89 as a login shell.
90 -N Do not start the server even if the command would normally
92 do so (for example new-session or start-server).
93 -S socket-path
95 Specify a full alternative path to the server socket. If
96 -S is specified, the default socket directory is not used
97 and any -L flag is ignored.
98 -u Write UTF-8 output to the terminal even if the first envi‐
100 ronment variable of LC_ALL, LC_CTYPE, or LANG that is set
101 does not contain "UTF-8" or "UTF8". This is equivalent to
102 -T UTF-8.
103 -T features Set terminal features for the client. This is a comma-sep‐
105 arated list of features. See the terminal-features option.
106 -v Request verbose logging. Log messages will be saved into
108 tmux-client-PID.log and tmux-server-PID.log files in the
109 current directory, where PID is the PID of the server or
110 client process. If -v is specified twice, an additional
111 tmux-out-PID.log file is generated with a copy of every‐
112 thing tmux writes to the terminal.
113 The SIGUSR2 signal may be sent to the tmux server process
115 to toggle logging between on (as if -v was given) and off.
116 -V Report the tmux version.
118 command [flags]
120 This specifies one of a set of commands used to control
121 tmux, as described in the following sections. If no com‐
122 mands are specified, the new-session command is assumed.
123
125 tmux may be controlled from an attached client by using a key combination
126 of a prefix key, ‘C-b’ (Ctrl-b) by default, followed by a command key.
127 The default command key bindings are:
129 C-b Send the prefix key (C-b) through to the application.
131 C-o Rotate the panes in the current window forwards.
132 C-z Suspend the tmux client.
133 ! Break the current pane out of the window.
134 " Split the current pane into two, top and bottom.
135 # List all paste buffers.
136 $ Rename the current session.
137 % Split the current pane into two, left and right.
138 & Kill the current window.
139 ' Prompt for a window index to select.
140 ( Switch the attached client to the previous session.
141 ) Switch the attached client to the next session.
142 , Rename the current window.
143 - Delete the most recently copied buffer of text.
144 . Prompt for an index to move the current window.
145 0 to 9 Select windows 0 to 9.
146 : Enter the tmux command prompt.
147 ; Move to the previously active pane.
148 = Choose which buffer to paste interactively from a list.
149 ? List all key bindings.
150 D Choose a client to detach.
151 L Switch the attached client back to the last session.
152 [ Enter copy mode to copy text or view the history.
153 ] Paste the most recently copied buffer of text.
154 c Create a new window.
155 d Detach the current client.
156 f Prompt to search for text in open windows.
157 i Display some information about the current window.
158 l Move to the previously selected window.
159 m Mark the current pane (see select-pane -m).
160 M Clear the marked pane.
161 n Change to the next window.
162 o Select the next pane in the current window.
163 p Change to the previous window.
164 q Briefly display pane indexes.
165 r Force redraw of the attached client.
166 s Select a new session for the attached client interac‐
167 tively.
168 t Show the time.
169 w Choose the current window interactively.
170 x Kill the current pane.
171 z Toggle zoom state of the current pane.
172 { Swap the current pane with the previous pane.
173 } Swap the current pane with the next pane.
174 ~ Show previous messages from tmux, if any.
175 Page Up Enter copy mode and scroll one page up.
176 Up, Down
177 Left, Right
178 Change to the pane above, below, to the left, or to the
179 right of the current pane.
180 M-1 to M-5 Arrange panes in one of the five preset layouts: even-
181 horizontal, even-vertical, main-horizontal, main-verti‐
182 cal, or tiled.
183 Space Arrange the current window in the next preset layout.
184 M-n Move to the next window with a bell or activity marker.
185 M-o Rotate the panes in the current window backwards.
186 M-p Move to the previous window with a bell or activity
187 marker.
188 C-Up, C-Down
189 C-Left, C-Right
190 Resize the current pane in steps of one cell.
191 M-Up, M-Down
192 M-Left, M-Right
193 Resize the current pane in steps of five cells.
194 Key bindings may be changed with the bind-key and unbind-key commands.
196
198 tmux supports a large number of commands which can be used to control its
199 behaviour. Each command is named and can accept zero or more flags and
200 arguments. They may be bound to a key with the bind-key command or run
201 from the shell prompt, a shell script, a configuration file or the com‐
202 mand prompt. For example, the same set-option command run from the shell
203 prompt, from ~/.tmux.conf and bound to a key may look like:
204 $ tmux set-option -g status-style bg=cyan
206 set-option -g status-style bg=cyan
208 bind-key C set-option -g status-style bg=cyan
210 Here, the command name is ‘set-option’, ‘-g’ is a flag and ‘status-style’
212 and ‘bg=cyan’ are arguments.
213 tmux distinguishes between command parsing and execution. In order to
215 execute a command, tmux needs it to be split up into its name and argu‐
216 ments. This is command parsing. If a command is run from the shell, the
217 shell parses it; from inside tmux or from a configuration file, tmux
218 does. Examples of when tmux parses commands are:
219 - in a configuration file;
221 - typed at the command prompt (see command-prompt);
223 - given to bind-key;
225 - passed as arguments to if-shell or confirm-before.
227 To execute commands, each client has a ‘command queue’. A global command
229 queue not attached to any client is used on startup for configuration
230 files like ~/.tmux.conf. Parsed commands added to the queue are executed
231 in order. Some commands, like if-shell and confirm-before, parse their
232 argument to create a new command which is inserted immediately after
233 themselves. This means that arguments can be parsed twice or more - once
234 when the parent command (such as if-shell) is parsed and again when it
235 parses and executes its command. Commands like if-shell, run-shell and
236 display-panes stop execution of subsequent commands on the queue until
237 something happens - if-shell and run-shell until a shell command finishes
238 and display-panes until a key is pressed. For example, the following
239 commands:
240 new-session; new-window
242 if-shell "true" "split-window"
243 kill-session
244 Will execute new-session, new-window, if-shell, the shell command
246 true(1), split-window and kill-session in that order.
247 The COMMANDS section lists the tmux commands and their arguments.
249
251 This section describes the syntax of commands parsed by tmux, for example
252 in a configuration file or at the command prompt. Note that when com‐
253 mands are entered into the shell, they are parsed by the shell - see for
254 example ksh(1) or csh(1).
255 Each command is terminated by a newline or a semicolon (;). Commands
257 separated by semicolons together form a ‘command sequence’ - if a command
258 in the sequence encounters an error, no subsequent commands are executed.
259 It is recommended that a semicolon used as a command separator should be
261 written as an individual token, for example from sh(1):
262 $ tmux neww \; splitw
264 Or:
266 $ tmux neww ';' splitw
268 Or from the tmux command prompt:
270 neww ; splitw
272 However, a trailing semicolon is also interpreted as a command separator,
274 for example in these sh(1) commands:
275 $ tmux neww\\; splitw
277 Or:
279 $ tmux 'neww;' splitw
281 As in these examples, when running tmux from the shell extra care must be
283 taken to properly quote semicolons:
284 1. Semicolons that should be interpreted as a command separator
286 should be escaped according to the shell conventions. For
287 sh(1) this typically means quoted (such as ‘neww ';' splitw’)
288 or escaped (such as ‘neww \\\\; splitw’).
289 2. Individual semicolons or trailing semicolons that should be
291 interpreted as arguments should be escaped twice: once accord‐
292 ing to the shell conventions and a second time for tmux; for
293 example:
294 $ tmux neww 'foo\\;' bar
296 $ tmux neww foo\\\\; bar
297 3. Semicolons that are not individual tokens or trailing another
299 token should only be escaped once according to shell conven‐
300 tions; for example:
301 $ tmux neww 'foo-;-bar'
303 $ tmux neww foo-\\;-bar
304 Comments are marked by the unquoted # character - any remaining text af‐
306 ter a comment is ignored until the end of the line.
307 If the last character of a line is \, the line is joined with the follow‐
309 ing line (the \ and the newline are completely removed). This is called
310 line continuation and applies both inside and outside quoted strings and
311 in comments, but not inside braces.
312 Command arguments may be specified as strings surrounded by single (')
314 quotes, double quotes (") or braces ({}). This is required when the ar‐
315 gument contains any special character. Single and double quoted strings
316 cannot span multiple lines except with line continuation. Braces can
317 span multiple lines.
318 Outside of quotes and inside double quotes, these replacements are per‐
320 formed:
321 - Environment variables preceded by $ are replaced with their
323 value from the global environment (see the GLOBAL AND SESSION
324 ENVIRONMENT section).
325 - A leading ~ or ~user is expanded to the home directory of the
327 current or specified user.
328 - \uXXXX or \uXXXXXXXX is replaced by the Unicode codepoint cor‐
330 responding to the given four or eight digit hexadecimal number.
331 - When preceded (escaped) by a \, the following characters are
333 replaced: \e by the escape character; \r by a carriage return;
334 \n by a newline; and \t by a tab.
335 - \ooo is replaced by a character of the octal value ooo. Three
337 octal digits are required, for example \001. The largest valid
338 character is \377.
339 - Any other characters preceded by \ are replaced by themselves
341 (that is, the \ is removed) and are not treated as having any
342 special meaning - so for example \; will not mark a command se‐
343 quence and \$ will not expand an environment variable.
344 Braces are parsed as a configuration file (so conditions such as ‘%if’
346 are processed) and then converted into a string. They are designed to
347 avoid the need for additional escaping when passing a group of tmux com‐
348 mands as an argument (for example to if-shell). These two examples pro‐
349 duce an identical command - note that no escaping is needed when using
350 {}:
351 if-shell true {
353 display -p 'brace-dollar-foo: }$foo'
354 }
355 if-shell true "display -p 'brace-dollar-foo: }\$foo'"
357 Braces may be enclosed inside braces, for example:
359 bind x if-shell "true" {
361 if-shell "true" {
362 display "true!"
363 }
364 }
365 Environment variables may be set by using the syntax ‘name=value’, for
367 example ‘HOME=/home/user’. Variables set during parsing are added to the
368 global environment. A hidden variable may be set with ‘%hidden’, for ex‐
369 ample:
370 %hidden MYVAR=42
372 Hidden variables are not passed to the environment of processes created
374 by tmux. See the GLOBAL AND SESSION ENVIRONMENT section.
375 Commands may be parsed conditionally by surrounding them with ‘%if’,
377 ‘%elif’, ‘%else’ and ‘%endif’. The argument to ‘%if’ and ‘%elif’ is ex‐
378 panded as a format (see FORMATS) and if it evaluates to false (zero or
379 empty), subsequent text is ignored until the closing ‘%elif’, ‘%else’ or
380 ‘%endif’. For example:
381 %if "#{==:#{host},myhost}"
383 set -g status-style bg=red
384 %elif "#{==:#{host},myotherhost}"
385 set -g status-style bg=green
386 %else
387 set -g status-style bg=blue
388 %endif
389 Will change the status line to red if running on ‘myhost’, green if run‐
391 ning on ‘myotherhost’, or blue if running on another host. Conditionals
392 may be given on one line, for example:
393 %if #{==:#{host},myhost} set -g status-style bg=red %endif
395
397 This section describes the commands supported by tmux. Most commands ac‐
398 cept the optional -t (and sometimes -s) argument with one of
399 target-client, target-session, target-window, or target-pane. These
400 specify the client, session, window or pane which a command should af‐
401 fect.
402 target-client should be the name of the client, typically the pty(4) file
404 to which the client is connected, for example either of /dev/ttyp1 or
405 ttyp1 for the client attached to /dev/ttyp1. If no client is specified,
406 tmux attempts to work out the client currently in use; if that fails, an
407 error is reported. Clients may be listed with the list-clients command.
408 target-session is tried as, in order:
410 1. A session ID prefixed with a $.
412 2. An exact name of a session (as listed by the list-sessions
414 command).
415 3. The start of a session name, for example ‘mysess’ would match
417 a session named ‘mysession’.
418 4. An fnmatch(3) pattern which is matched against the session
420 name.
421 If the session name is prefixed with an ‘=’, only an exact match is ac‐
423 cepted (so ‘=mysess’ will only match exactly ‘mysess’, not ‘mysession’).
424 If a single session is found, it is used as the target session; multiple
426 matches produce an error. If a session is omitted, the current session
427 is used if available; if no current session is available, the most re‐
428 cently used is chosen.
429 target-window (or src-window or dst-window) specifies a window in the
431 form session:window. session follows the same rules as for
432 target-session, and window is looked for in order as:
433 1. A special token, listed below.
435 2. A window index, for example ‘mysession:1’ is window 1 in ses‐
437 sion ‘mysession’.
438 3. A window ID, such as @1.
440 4. An exact window name, such as ‘mysession:mywindow’.
442 5. The start of a window name, such as ‘mysession:mywin’.
444 6. As an fnmatch(3) pattern matched against the window name.
446 Like sessions, a ‘=’ prefix will do an exact match only. An empty window
448 name specifies the next unused index if appropriate (for example the
449 new-window and link-window commands) otherwise the current window in
450 session is chosen.
451 The following special tokens are available to indicate particular win‐
453 dows. Each has a single-character alternative form.
454 Token Meaning
456 {start} ^ The lowest-numbered window
457 {end} $ The highest-numbered window
458 {last} ! The last (previously current) window
459 {next} + The next window by number
460 {previous} - The previous window by number
461 target-pane (or src-pane or dst-pane) may be a pane ID or takes a similar
463 form to target-window but with the optional addition of a period followed
464 by a pane index or pane ID, for example: ‘mysession:mywindow.1’. If the
465 pane index is omitted, the currently active pane in the specified window
466 is used. The following special tokens are available for the pane index:
467 Token Meaning
469 {last} ! The last (previously active) pane
470 {next} + The next pane by number
471 {previous} - The previous pane by number
472 {top} The top pane
473 {bottom} The bottom pane
474 {left} The leftmost pane
475 {right} The rightmost pane
476 {top-left} The top-left pane
477 {top-right} The top-right pane
478 {bottom-left} The bottom-left pane
479 {bottom-right} The bottom-right pane
480 {up-of} The pane above the active pane
481 {down-of} The pane below the active pane
482 {left-of} The pane to the left of the active pane
483 {right-of} The pane to the right of the active pane
484 The tokens ‘+’ and ‘-’ may be followed by an offset, for example:
486 select-window -t:+2
488 In addition, target-session, target-window or target-pane may consist en‐
490 tirely of the token ‘{mouse}’ (alternative form ‘=’) to specify the ses‐
491 sion, window or pane where the most recent mouse event occurred (see the
492 MOUSE SUPPORT section) or ‘{marked}’ (alternative form ‘~’) to specify
493 the marked pane (see select-pane -m).
494 Sessions, window and panes are each numbered with a unique ID; session
496 IDs are prefixed with a ‘$’, windows with a ‘@’, and panes with a ‘%’.
497 These are unique and are unchanged for the life of the session, window or
498 pane in the tmux server. The pane ID is passed to the child process of
499 the pane in the TMUX_PANE environment variable. IDs may be displayed us‐
500 ing the ‘session_id’, ‘window_id’, or ‘pane_id’ formats (see the FORMATS
501 section) and the display-message, list-sessions, list-windows or
502 list-panes commands.
503 shell-command arguments are sh(1) commands. This may be a single argu‐
505 ment passed to the shell, for example:
506 new-window 'vi ~/.tmux.conf'
508 Will run:
510 /bin/sh -c 'vi ~/.tmux.conf'
512 Additionally, the new-window, new-session, split-window, respawn-window
514 and respawn-pane commands allow shell-command to be given as multiple ar‐
515 guments and executed directly (without ‘sh -c’). This can avoid issues
516 with shell quoting. For example:
517 $ tmux new-window vi ~/.tmux.conf
519 Will run vi(1) directly without invoking the shell.
521 command [arguments] refers to a tmux command, either passed with the com‐
523 mand and arguments separately, for example:
524 bind-key F1 set-option status off
526 Or passed as a single string argument in .tmux.conf, for example:
528 bind-key F1 { set-option status off }
530 Example tmux commands include:
532 refresh-client -t/dev/ttyp2
534 rename-session -tfirst newname
536 set-option -wt:0 monitor-activity on
538 new-window ; split-window -d
540 bind-key R source-file ~/.tmux.conf \; \
542 display-message "source-file done"
543 Or from sh(1):
545 $ tmux kill-window -t :1
547 $ tmux new-window \; split-window -d
549 $ tmux new-session -d 'vi ~/.tmux.conf' \; split-window -d \; attach
551
553 The tmux server manages clients, sessions, windows and panes. Clients
554 are attached to sessions to interact with them, either when they are cre‐
555 ated with the new-session command, or later with the attach-session com‐
556 mand. Each session has one or more windows linked into it. Windows may
557 be linked to multiple sessions and are made up of one or more panes, each
558 of which contains a pseudo terminal. Commands for creating, linking and
559 otherwise manipulating windows are covered in the WINDOWS AND PANES sec‐
560 tion.
561 The following commands are available to manage clients and sessions:
563 attach-session [-dErx] [-c working-directory] [-f flags] [-t
565 target-session]
566 (alias: attach)
567 If run from outside tmux, create a new client in the current ter‐
568 minal and attach it to target-session. If used from inside,
569 switch the current client. If -d is specified, any other clients
570 attached to the session are detached. If -x is given, send
571 SIGHUP to the parent process of the client as well as detaching
572 the client, typically causing it to exit. -f sets a comma-sepa‐
573 rated list of client flags. The flags are:
574 active-pane
576 the client has an independent active pane
577 ignore-size
579 the client does not affect the size of other clients
580 no-output
582 the client does not receive pane output in control mode
583 pause-after=seconds
585 output is paused once the pane is seconds behind in con‐
586 trol mode
587 read-only
589 the client is read-only
590 wait-exit
592 wait for an empty line input before exiting in control
593 mode
594 A leading ‘!’ turns a flag off if the client is already attached.
596 -r is an alias for -f read-only,ignore-size. When a client is
597 read-only, only keys bound to the detach-client or switch-client
598 commands have any effect. A client with the active-pane flag al‐
599 lows the active pane to be selected independently of the window's
600 active pane used by clients without the flag. This only affects
601 the cursor position and commands issued from the client; other
602 features such as hooks and styles continue to use the window's
603 active pane.
604 If no server is started, attach-session will attempt to start it;
606 this will fail unless sessions are created in the configuration
607 file.
608 The target-session rules for attach-session are slightly ad‐
610 justed: if tmux needs to select the most recently used session,
611 it will prefer the most recently used unattached session.
612 -c will set the session working directory (used for new windows)
614 to working-directory.
615 If -E is used, the update-environment option will not be applied.
617 detach-client [-aP] [-E shell-command] [-s target-session] [-t
619 target-client]
620 (alias: detach)
621 Detach the current client if bound to a key, the client specified
622 with -t, or all clients currently attached to the session speci‐
623 fied by -s. The -a option kills all but the client given with
624 -t. If -P is given, send SIGHUP to the parent process of the
625 client, typically causing it to exit. With -E, run shell-command
626 to replace the client.
627 has-session [-t target-session]
629 (alias: has)
630 Report an error and exit with 1 if the specified session does not
631 exist. If it does exist, exit with 0.
632 kill-server
634 Kill the tmux server and clients and destroy all sessions.
635 kill-session [-aC] [-t target-session]
637 Destroy the given session, closing any windows linked to it and
638 no other sessions, and detaching all clients attached to it. If
639 -a is given, all sessions but the specified one is killed. The
640 -C flag clears alerts (bell, activity, or silence) in all windows
641 linked to the session.
642 list-clients [-F format] [-t target-session]
644 (alias: lsc)
645 List all clients attached to the server. For the meaning of the
646 -F flag, see the FORMATS section. If target-session is speci‐
647 fied, list only clients connected to that session.
648 list-commands [-F format] [command]
650 (alias: lscm)
651 List the syntax of command or - if omitted - of all commands sup‐
652 ported by tmux.
653 list-sessions [-F format] [-f filter]
655 (alias: ls)
656 List all sessions managed by the server. -F specifies the format
657 of each line and -f a filter. Only sessions for which the filter
658 is true are shown. See the FORMATS section.
659 lock-client [-t target-client]
661 (alias: lockc)
662 Lock target-client, see the lock-server command.
663 lock-session [-t target-session]
665 (alias: locks)
666 Lock all clients attached to target-session.
667 new-session [-AdDEPX] [-c start-directory] [-e environment] [-f flags]
669 [-F format] [-n window-name] [-s session-name] [-t group-name]
670 [-x width] [-y height] [shell-command]
671 (alias: new)
672 Create a new session with name session-name.
673 The new session is attached to the current terminal unless -d is
675 given. window-name and shell-command are the name of and shell
676 command to execute in the initial window. With -d, the initial
677 size comes from the global default-size option; -x and -y can be
678 used to specify a different size. ‘-’ uses the size of the cur‐
679 rent client if any. If -x or -y is given, the default-size op‐
680 tion is set for the session. -f sets a comma-separated list of
681 client flags (see attach-session).
682 If run from a terminal, any termios(4) special characters are
684 saved and used for new windows in the new session.
685 The -A flag makes new-session behave like attach-session if
687 session-name already exists; in this case, -D behaves like -d to
688 attach-session, and -X behaves like -x to attach-session.
689 If -t is given, it specifies a session group. Sessions in the
691 same group share the same set of windows - new windows are linked
692 to all sessions in the group and any windows closed removed from
693 all sessions. The current and previous window and any session
694 options remain independent and any session in a group may be
695 killed without affecting the others. The group-name argument may
696 be:
697 1. the name of an existing group, in which case the new ses‐
699 sion is added to that group;
700 2. the name of an existing session - the new session is
702 added to the same group as that session, creating a new
703 group if necessary;
704 3. the name for a new group containing only the new session.
706 -n and shell-command are invalid if -t is used.
708 The -P option prints information about the new session after it
710 has been created. By default, it uses the format
711 ‘#{session_name}:’ but a different format may be specified with
712 -F.
713 If -E is used, the update-environment option will not be applied.
715 -e takes the form ‘VARIABLE=value’ and sets an environment vari‐
716 able for the newly created session; it may be specified multiple
717 times.
718 refresh-client [-cDlLRSU] [-A pane:state] [-B name:what:format] [-C XxY]
720 [-f flags] [-t target-client] [adjustment]
721 (alias: refresh)
722 Refresh the current client if bound to a key, or a single client
723 if one is given with -t. If -S is specified, only update the
724 client's status line.
725 The -U, -D, -L -R, and -c flags allow the visible portion of a
727 window which is larger than the client to be changed. -U moves
728 the visible part up by adjustment rows and -D down, -L left by
729 adjustment columns and -R right. -c returns to tracking the cur‐
730 sor automatically. If adjustment is omitted, 1 is used. Note
731 that the visible position is a property of the client not of the
732 window, changing the current window in the attached session will
733 reset it.
734 -C sets the width and height of a control mode client. -A allows
736 a control mode client to trigger actions on a pane. The argument
737 is a pane ID (with leading ‘%’), a colon, then one of ‘on’,
738 ‘off’, ‘continue’ or ‘pause’. If ‘off’, tmux will not send out‐
739 put from the pane to the client and if all clients have turned
740 the pane off, will stop reading from the pane. If ‘continue’,
741 tmux will return to sending output to the pane if it was paused
742 (manually or with the pause-after flag). If ‘pause’, tmux will
743 pause the pane. -A may be given multiple times for different
744 panes.
745 -B sets a subscription to a format for a control mode client.
747 The argument is split into three items by colons: name is a name
748 for the subscription; what is a type of item to subscribe to;
749 format is the format. After a subscription is added, changes to
750 the format are reported with the %subscription-changed notifica‐
751 tion, at most once a second. If only the name is given, the sub‐
752 scription is removed. what may be empty to check the format only
753 for the attached session, or one of: a pane ID such as ‘%0’; ‘%*’
754 for all panes in the attached session; a window ID such as ‘@0’;
755 or ‘@*’ for all windows in the attached session.
756 -f sets a comma-separated list of client flags, see
758 attach-session.
759 -l requests the clipboard from the client using the xterm(1) es‐
761 cape sequence and stores it in a new paste buffer.
762 -L, -R, -U and -D move the visible portion of the window left,
764 right, up or down by adjustment, if the window is larger than the
765 client. -c resets so that the position follows the cursor. See
766 the window-size option.
767 rename-session [-t target-session] new-name
769 (alias: rename)
770 Rename the session to new-name.
771 show-messages [-JT] [-t target-client]
773 (alias: showmsgs)
774 Show server messages or information. Messages are stored, up to
775 a maximum of the limit set by the message-limit server option.
776 -J and -T show debugging information about jobs and terminals.
777 source-file [-Fnqv] path ...
779 (alias: source)
780 Execute commands from one or more files specified by path (which
781 may be glob(7) patterns). If -F is present, then path is ex‐
782 panded as a format. If -q is given, no error will be returned if
783 path does not exist. With -n, the file is parsed but no commands
784 are executed. -v shows the parsed commands and line numbers if
785 possible.
786 start-server
788 (alias: start)
789 Start the tmux server, if not already running, without creating
790 any sessions.
791 Note that as by default the tmux server will exit with no ses‐
793 sions, this is only useful if a session is created in
794 ~/.tmux.conf, exit-empty is turned off, or another command is run
795 as part of the same command sequence. For example:
796 $ tmux start \; show -g
798 suspend-client [-t target-client]
800 (alias: suspendc)
801 Suspend a client by sending SIGTSTP (tty stop).
802 switch-client [-ElnprZ] [-c target-client] [-t target-session] [-T
804 key-table]
805 (alias: switchc)
806 Switch the current session for client target-client to
807 target-session. As a special case, -t may refer to a pane (a
808 target that contains ‘:’, ‘.’ or ‘%’), to change session, window
809 and pane. In that case, -Z keeps the window zoomed if it was
810 zoomed. If -l, -n or -p is used, the client is moved to the
811 last, next or previous session respectively. -r toggles the
812 client read-only and ignore-size flags (see the attach-session
813 command).
814 If -E is used, update-environment option will not be applied.
816 -T sets the client's key table; the next key from the client will
818 be interpreted from key-table. This may be used to configure
819 multiple prefix keys, or to bind commands to sequences of keys.
820 For example, to make typing ‘abc’ run the list-keys command:
821 bind-key -Ttable2 c list-keys
823 bind-key -Ttable1 b switch-client -Ttable2
824 bind-key -Troot a switch-client -Ttable1
825
827 Each window displayed by tmux may be split into one or more panes; each
828 pane takes up a certain area of the display and is a separate terminal.
829 A window may be split into panes using the split-window command. Windows
830 may be split horizontally (with the -h flag) or vertically. Panes may be
831 resized with the resize-pane command (bound to ‘C-Up’, ‘C-Down’ ‘C-Left’
832 and ‘C-Right’ by default), the current pane may be changed with the
833 select-pane command and the rotate-window and swap-pane commands may be
834 used to swap panes without changing their position. Panes are numbered
835 beginning from zero in the order they are created.
836 By default, a tmux pane permits direct access to the terminal contained
838 in the pane. A pane may also be put into one of several modes:
839 - Copy mode, which permits a section of a window or its history
841 to be copied to a paste buffer for later insertion into another
842 window. This mode is entered with the copy-mode command, bound
843 to ‘[’ by default. Copied text can be pasted with the
844 paste-buffer command, bound to ‘]’.
845 - View mode, which is like copy mode but is entered when a com‐
847 mand that produces output, such as list-keys, is executed from
848 a key binding.
849 - Choose mode, which allows an item to be chosen from a list.
851 This may be a client, a session or window or pane, or a buffer.
852 This mode is entered with the choose-buffer, choose-client and
853 choose-tree commands.
854 In copy mode an indicator is displayed in the top-right corner of the
856 pane with the current position and the number of lines in the history.
857 Commands are sent to copy mode using the -X flag to the send-keys com‐
859 mand. When a key is pressed, copy mode automatically uses one of two key
860 tables, depending on the mode-keys option: copy-mode for emacs, or
861 copy-mode-vi for vi. Key tables may be viewed with the list-keys com‐
862 mand.
863 The following commands are supported in copy mode:
865 Command vi emacs
867 append-selection
868 append-selection-and-cancel A
869 back-to-indentation ^ M-m
870 begin-selection Space C-Space
871 bottom-line L
872 cancel q Escape
873 clear-selection Escape C-g
874 copy-end-of-line [<prefix>] D C-k
875 copy-line [<prefix>]
876 copy-pipe [<command>] [<prefix>]
877 copy-pipe-no-clear [<command>] [<prefix>]
878 copy-pipe-and-cancel [<command>] [<prefix>]
879 copy-selection [<prefix>]
880 copy-selection-no-clear [<prefix>]
881 copy-selection-and-cancel [<prefix>] Enter M-w
882 cursor-down j Down
883 cursor-down-and-cancel
884 cursor-left h Left
885 cursor-right l Right
886 cursor-up k Up
887 end-of-line $ C-e
888 goto-line <line> : g
889 halfpage-down C-d M-Down
890 halfpage-down-and-cancel
891 halfpage-up C-u M-Up
892 history-bottom G M->
893 history-top g M-<
894 jump-again ; ;
895 jump-backward <to> F F
896 jump-forward <to> f f
897 jump-reverse , ,
898 jump-to-backward <to> T
899 jump-to-forward <to> t
900 jump-to-mark M-x M-x
901 middle-line M M-r
902 next-matching-bracket % M-C-f
903 next-paragraph } M-}
904 next-space W
905 next-space-end E
906 next-word w
907 next-word-end e M-f
908 other-end o
909 page-down C-f PageDown
910 page-down-and-cancel
911 page-up C-b PageUp
912 pipe [<command>] [<prefix>]
913 pipe-no-clear [<command>] [<prefix>]
914 pipe-and-cancel [<command>] [<prefix>]
915 previous-matching-bracket M-C-b
916 previous-paragraph { M-{
917 previous-space B
918 previous-word b M-b
919 rectangle-on
920 rectangle-off
921 rectangle-toggle v R
922 refresh-from-pane r r
923 scroll-down C-e C-Down
924 scroll-down-and-cancel
925 scroll-up C-y C-Up
926 search-again n n
927 search-backward <for> ?
928 search-backward-incremental <for> C-r
929 search-backward-text <for>
930 search-forward <for> /
931 search-forward-incremental <for> C-s
932 search-forward-text <for>
933 search-reverse N N
934 select-line V
935 select-word
936 set-mark X X
937 start-of-line 0 C-a
938 stop-selection
939 top-line H M-R
940 The search commands come in several varieties: ‘search-forward’ and
942 ‘search-backward’ search for a regular expression; the ‘-text’ variants
943 search for a plain text string rather than a regular expression;
944 ‘-incremental’ perform an incremental search and expect to be used with
945 the -i flag to the command-prompt command. ‘search-again’ repeats the
946 last search and ‘search-reverse’ does the same but reverses the direction
947 (forward becomes backward and backward becomes forward).
948 Copy commands may take an optional buffer prefix argument which is used
950 to generate the buffer name (the default is ‘buffer’ so buffers are named
951 ‘buffer0’, ‘buffer1’ and so on). Pipe commands take a command argument
952 which is the command to which the selected text is piped. ‘copy-pipe’
953 variants also copy the selection. The ‘-and-cancel’ variants of some
954 commands exit copy mode after they have completed (for copy commands) or
955 when the cursor reaches the bottom (for scrolling commands). ‘-no-clear’
956 variants do not clear the selection.
957 The next and previous word keys use space and the ‘-’, ‘_’ and ‘@’ char‐
959 acters as word delimiters by default, but this can be adjusted by setting
960 the word-separators session option. Next word moves to the start of the
961 next word, next word end to the end of the next word and previous word to
962 the start of the previous word. The three next and previous space keys
963 work similarly but use a space alone as the word separator.
964 The jump commands enable quick movement within a line. For instance,
966 typing ‘f’ followed by ‘/’ will move the cursor to the next ‘/’ character
967 on the current line. A ‘;’ will then jump to the next occurrence.
968 Commands in copy mode may be prefaced by an optional repeat count. With
970 vi key bindings, a prefix is entered using the number keys; with emacs,
971 the Alt (meta) key and a number begins prefix entry.
972 The synopsis for the copy-mode command is:
974 copy-mode [-eHMqu] [-s src-pane] [-t target-pane]
976 Enter copy mode. The -u option scrolls one page up. -M begins a
977 mouse drag (only valid if bound to a mouse key binding, see MOUSE
978 SUPPORT). -H hides the position indicator in the top right. -q
979 cancels copy mode and any other modes. -s copies from src-pane
980 instead of target-pane.
981 -e specifies that scrolling to the bottom of the history (to the
983 visible screen) should exit copy mode. While in copy mode,
984 pressing a key other than those used for scrolling will disable
985 this behaviour. This is intended to allow fast scrolling through
986 a pane's history, for example with:
987 bind PageUp copy-mode -eu
989 A number of preset arrangements of panes are available, these are called
991 layouts. These may be selected with the select-layout command or cycled
992 with next-layout (bound to ‘Space’ by default); once a layout is chosen,
993 panes within it may be moved and resized as normal.
994 The following layouts are supported:
996 even-horizontal
998 Panes are spread out evenly from left to right across the window.
999 even-vertical
1001 Panes are spread evenly from top to bottom.
1002 main-horizontal
1004 A large (main) pane is shown at the top of the window and the re‐
1005 maining panes are spread from left to right in the leftover space
1006 at the bottom. Use the main-pane-height window option to specify
1007 the height of the top pane.
1008 main-vertical
1010 Similar to main-horizontal but the large pane is placed on the
1011 left and the others spread from top to bottom along the right.
1012 See the main-pane-width window option.
1013 tiled Panes are spread out as evenly as possible over the window in
1015 both rows and columns.
1016 In addition, select-layout may be used to apply a previously used layout
1018 - the list-windows command displays the layout of each window in a form
1019 suitable for use with select-layout. For example:
1020 $ tmux list-windows
1022 0: ksh [159x48]
1023 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
1024 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
1025 tmux automatically adjusts the size of the layout for the current window
1027 size. Note that a layout cannot be applied to a window with more panes
1028 than that from which the layout was originally defined.
1029 Commands related to windows and panes are as follows:
1031 break-pane [-abdP] [-F format] [-n window-name] [-s src-pane] [-t
1033 dst-window]
1034 (alias: breakp)
1035 Break src-pane off from its containing window to make it the only
1036 pane in dst-window. With -a or -b, the window is moved to the
1037 next index after or before (existing windows are moved if neces‐
1038 sary). If -d is given, the new window does not become the cur‐
1039 rent window. The -P option prints information about the new win‐
1040 dow after it has been created. By default, it uses the format
1041 ‘#{session_name}:#{window_index}.#{pane_index}’ but a different
1042 format may be specified with -F.
1043 capture-pane [-aepPqCJN] [-b buffer-name] [-E end-line] [-S start-line]
1045 [-t target-pane]
1046 (alias: capturep)
1047 Capture the contents of a pane. If -p is given, the output goes
1048 to stdout, otherwise to the buffer specified with -b or a new
1049 buffer if omitted. If -a is given, the alternate screen is used,
1050 and the history is not accessible. If no alternate screen ex‐
1051 ists, an error will be returned unless -q is given. If -e is
1052 given, the output includes escape sequences for text and back‐
1053 ground attributes. -C also escapes non-printable characters as
1054 octal \xxx. -N preserves trailing spaces at each line's end and
1055 -J preserves trailing spaces and joins any wrapped lines. -P
1056 captures only any output that the pane has received that is the
1057 beginning of an as-yet incomplete escape sequence.
1058 -S and -E specify the starting and ending line numbers, zero is
1060 the first line of the visible pane and negative numbers are lines
1061 in the history. ‘-’ to -S is the start of the history and to -E
1062 the end of the visible pane. The default is to capture only the
1063 visible contents of the pane.
1064 choose-client [-NrZ] [-F format] [-f filter] [-K key-format] [-O
1066 sort-order] [-t target-pane] [template]
1067 Put a pane into client mode, allowing a client to be selected in‐
1068 teractively from a list. Each client is shown on one line. A
1069 shortcut key is shown on the left in brackets allowing for imme‐
1070 diate choice, or the list may be navigated and an item chosen or
1071 otherwise manipulated using the keys below. -Z zooms the pane.
1072 The following keys may be used in client mode:
1073 Key Function
1075 Enter Choose selected client
1076 Up Select previous client
1077 Down Select next client
1078 C-s Search by name
1079 n Repeat last search
1080 t Toggle if client is tagged
1081 T Tag no clients
1082 C-t Tag all clients
1083 d Detach selected client
1084 D Detach tagged clients
1085 x Detach and HUP selected client
1086 X Detach and HUP tagged clients
1087 z Suspend selected client
1088 Z Suspend tagged clients
1089 f Enter a format to filter items
1090 O Change sort field
1091 r Reverse sort order
1092 v Toggle preview
1093 q Exit mode
1094 After a client is chosen, ‘%%’ is replaced by the client name in
1096 template and the result executed as a command. If template is
1097 not given, "detach-client -t '%%'" is used.
1098 -O specifies the initial sort field: one of ‘name’, ‘size’,
1100 ‘creation’, or ‘activity’. -r reverses the sort order. -f spec‐
1101 ifies an initial filter: the filter is a format - if it evaluates
1102 to zero, the item in the list is not shown, otherwise it is
1103 shown. If a filter would lead to an empty list, it is ignored.
1104 -F specifies the format for each item in the list and -K a format
1105 for each shortcut key; both are evaluated once for each line. -N
1106 starts without the preview. This command works only if at least
1107 one client is attached.
1108 choose-tree [-GNrswZ] [-F format] [-f filter] [-K key-format] [-O
1110 sort-order] [-t target-pane] [template]
1111 Put a pane into tree mode, where a session, window or pane may be
1112 chosen interactively from a tree. Each session, window or pane
1113 is shown on one line. A shortcut key is shown on the left in
1114 brackets allowing for immediate choice, or the tree may be navi‐
1115 gated and an item chosen or otherwise manipulated using the keys
1116 below. -s starts with sessions collapsed and -w with windows
1117 collapsed. -Z zooms the pane. The following keys may be used in
1118 tree mode:
1119 Key Function
1121 Enter Choose selected item
1122 Up Select previous item
1123 Down Select next item
1124 + Expand selected item
1125 - Collapse selected item
1126 M-+ Expand all items
1127 M-- Collapse all items
1128 x Kill selected item
1129 X Kill tagged items
1130 < Scroll list of previews left
1131 > Scroll list of previews right
1132 C-s Search by name
1133 m Set the marked pane
1134 M Clear the marked pane
1135 n Repeat last search
1136 t Toggle if item is tagged
1137 T Tag no items
1138 C-t Tag all items
1139 : Run a command for each tagged item
1140 f Enter a format to filter items
1141 H Jump to the starting pane
1142 O Change sort field
1143 r Reverse sort order
1144 v Toggle preview
1145 q Exit mode
1146 After a session, window or pane is chosen, ‘%%’ is replaced by
1148 the target in template and the result executed as a command. If
1149 template is not given, "switch-client -t '%%'" is used.
1150 -O specifies the initial sort field: one of ‘index’, ‘name’, or
1152 ‘time’. -r reverses the sort order. -f specifies an initial
1153 filter: the filter is a format - if it evaluates to zero, the
1154 item in the list is not shown, otherwise it is shown. If a fil‐
1155 ter would lead to an empty list, it is ignored. -F specifies the
1156 format for each item in the tree and -K a format for each short‐
1157 cut key; both are evaluated once for each line. -N starts with‐
1158 out the preview. -G includes all sessions in any session groups
1159 in the tree rather than only the first. This command works only
1160 if at least one client is attached.
1161 customize-mode [-NZ] [-F format] [-f filter] [-t target-pane] [template]
1163 Put a pane into customize mode, where options and key bindings
1164 may be browsed and modified from a list. Option values in the
1165 list are shown for the active pane in the current window. -Z
1166 zooms the pane. The following keys may be used in customize
1167 mode:
1168 Key Function
1170 Enter Set pane, window, session or global option value
1171 Up Select previous item
1172 Down Select next item
1173 + Expand selected item
1174 - Collapse selected item
1175 M-+ Expand all items
1176 M-- Collapse all items
1177 s Set option value or key attribute
1178 S Set global option value
1179 w Set window option value, if option is for pane and
1180 window
1181 d Set an option or key to the default
1182 D Set tagged options and tagged keys to the default
1183 u Unset an option (set to default value if global) or
1184 unbind a key
1185 U Unset tagged options and unbind tagged keys
1186 C-s Search by name
1187 n Repeat last search
1188 t Toggle if item is tagged
1189 T Tag no items
1190 C-t Tag all items
1191 f Enter a format to filter items
1192 v Toggle option information
1193 q Exit mode
1194 -f specifies an initial filter: the filter is a format - if it
1196 evaluates to zero, the item in the list is not shown, otherwise
1197 it is shown. If a filter would lead to an empty list, it is ig‐
1198 nored. -F specifies the format for each item in the tree. -N
1199 starts without the option information. This command works only
1200 if at least one client is attached.
1201 display-panes [-bN] [-d duration] [-t target-client] [template]
1203 (alias: displayp)
1204 Display a visible indicator of each pane shown by target-client.
1205 See the display-panes-colour and display-panes-active-colour ses‐
1206 sion options. The indicator is closed when a key is pressed (un‐
1207 less -N is given) or duration milliseconds have passed. If -d is
1208 not given, display-panes-time is used. A duration of zero means
1209 the indicator stays until a key is pressed. While the indicator
1210 is on screen, a pane may be chosen with the ‘0’ to ‘9’ keys,
1211 which will cause template to be executed as a command with ‘%%’
1212 substituted by the pane ID. The default template is "select-pane
1213 -t '%%'". With -b, other commands are not blocked from running
1214 until the indicator is closed.
1215 find-window [-iCNrTZ] [-t target-pane] match-string
1217 (alias: findw)
1218 Search for a fnmatch(3) pattern or, with -r, regular expression
1219 match-string in window names, titles, and visible content (but
1220 not history). The flags control matching behavior: -C matches
1221 only visible window contents, -N matches only the window name and
1222 -T matches only the window title. -i makes the search ignore
1223 case. The default is -CNT. -Z zooms the pane.
1224 This command works only if at least one client is attached.
1226 join-pane [-bdfhv] [-l size] [-s src-pane] [-t dst-pane]
1228 (alias: joinp)
1229 Like split-window, but instead of splitting dst-pane and creating
1230 a new pane, split it and move src-pane into the space. This can
1231 be used to reverse break-pane. The -b option causes src-pane to
1232 be joined to left of or above dst-pane.
1233 If -s is omitted and a marked pane is present (see select-pane
1235 -m), the marked pane is used rather than the current pane.
1236 kill-pane [-a] [-t target-pane]
1238 (alias: killp)
1239 Destroy the given pane. If no panes remain in the containing
1240 window, it is also destroyed. The -a option kills all but the
1241 pane given with -t.
1242 kill-window [-a] [-t target-window]
1244 (alias: killw)
1245 Kill the current window or the window at target-window, removing
1246 it from any sessions to which it is linked. The -a option kills
1247 all but the window given with -t.
1248 last-pane [-deZ] [-t target-window]
1250 (alias: lastp)
1251 Select the last (previously selected) pane. -Z keeps the window
1252 zoomed if it was zoomed. -e enables or -d disables input to the
1253 pane.
1254 last-window [-t target-session]
1256 (alias: last)
1257 Select the last (previously selected) window. If no
1258 target-session is specified, select the last window of the cur‐
1259 rent session.
1260 link-window [-abdk] [-s src-window] [-t dst-window]
1262 (alias: linkw)
1263 Link the window at src-window to the specified dst-window. If
1264 dst-window is specified and no such window exists, the src-window
1265 is linked there. With -a or -b the window is moved to the next
1266 index after or before dst-window (existing windows are moved if
1267 necessary). If -k is given and dst-window exists, it is killed,
1268 otherwise an error is generated. If -d is given, the newly
1269 linked window is not selected.
1270 list-panes [-as] [-F format] [-f filter] [-t target]
1272 (alias: lsp)
1273 If -a is given, target is ignored and all panes on the server are
1274 listed. If -s is given, target is a session (or the current ses‐
1275 sion). If neither is given, target is a window (or the current
1276 window). -F specifies the format of each line and -f a filter.
1277 Only panes for which the filter is true are shown. See the
1278 FORMATS section.
1279 list-windows [-a] [-F format] [-f filter] [-t target-session]
1281 (alias: lsw)
1282 If -a is given, list all windows on the server. Otherwise, list
1283 windows in the current session or in target-session. -F speci‐
1284 fies the format of each line and -f a filter. Only windows for
1285 which the filter is true are shown. See the FORMATS section.
1286 move-pane [-bdfhv] [-l size] [-s src-pane] [-t dst-pane]
1288 (alias: movep)
1289 Does the same as join-pane.
1290 move-window [-abrdk] [-s src-window] [-t dst-window]
1292 (alias: movew)
1293 This is similar to link-window, except the window at src-window
1294 is moved to dst-window. With -r, all windows in the session are
1295 renumbered in sequential order, respecting the base-index option.
1296 new-window [-abdkPS] [-c start-directory] [-e environment] [-F format]
1298 [-n window-name] [-t target-window] [shell-command]
1299 (alias: neww)
1300 Create a new window. With -a or -b, the new window is inserted
1301 at the next index after or before the specified target-window,
1302 moving windows up if necessary; otherwise target-window is the
1303 new window location.
1304 If -d is given, the session does not make the new window the cur‐
1306 rent window. target-window represents the window to be created;
1307 if the target already exists an error is shown, unless the -k
1308 flag is used, in which case it is destroyed. If -S is given and
1309 a window named window-name already exists, it is selected (unless
1310 -d is also given in which case the command does nothing).
1311 shell-command is the command to execute. If shell-command is not
1313 specified, the value of the default-command option is used. -c
1314 specifies the working directory in which the new window is cre‐
1315 ated.
1316 When the shell command completes, the window closes. See the
1318 remain-on-exit option to change this behaviour.
1319 -e takes the form ‘VARIABLE=value’ and sets an environment vari‐
1321 able for the newly created window; it may be specified multiple
1322 times.
1323 The TERM environment variable must be set to ‘screen’ or ‘tmux’
1325 for all programs running inside tmux. New windows will automati‐
1326 cally have ‘TERM=screen’ added to their environment, but care
1327 must be taken not to reset this in shell start-up files or by the
1328 -e option.
1329 The -P option prints information about the new window after it
1331 has been created. By default, it uses the format
1332 ‘#{session_name}:#{window_index}’ but a different format may be
1333 specified with -F.
1334 next-layout [-t target-window]
1336 (alias: nextl)
1337 Move a window to the next layout and rearrange the panes to fit.
1338 next-window [-a] [-t target-session]
1340 (alias: next)
1341 Move to the next window in the session. If -a is used, move to
1342 the next window with an alert.
1343 pipe-pane [-IOo] [-t target-pane] [shell-command]
1345 (alias: pipep)
1346 Pipe output sent by the program in target-pane to a shell command
1347 or vice versa. A pane may only be connected to one command at a
1348 time, any existing pipe is closed before shell-command is exe‐
1349 cuted. The shell-command string may contain the special charac‐
1350 ter sequences supported by the status-left option. If no
1351 shell-command is given, the current pipe (if any) is closed.
1352 -I and -O specify which of the shell-command output streams are
1354 connected to the pane: with -I stdout is connected (so anything
1355 shell-command prints is written to the pane as if it were typed);
1356 with -O stdin is connected (so any output in the pane is piped to
1357 shell-command). Both may be used together and if neither are
1358 specified, -O is used.
1359 The -o option only opens a new pipe if no previous pipe exists,
1361 allowing a pipe to be toggled with a single key, for example:
1362 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
1364 previous-layout [-t target-window]
1366 (alias: prevl)
1367 Move to the previous layout in the session.
1368 previous-window [-a] [-t target-session]
1370 (alias: prev)
1371 Move to the previous window in the session. With -a, move to the
1372 previous window with an alert.
1373 rename-window [-t target-window] new-name
1375 (alias: renamew)
1376 Rename the current window, or the window at target-window if
1377 specified, to new-name.
1378 resize-pane [-DLMRTUZ] [-t target-pane] [-x width] [-y height]
1380 [adjustment]
1381 (alias: resizep)
1382 Resize a pane, up, down, left or right by adjustment with -U, -D,
1383 -L or -R, or to an absolute size with -x or -y. The adjustment
1384 is given in lines or columns (the default is 1); -x and -y may be
1385 a given as a number of lines or columns or followed by ‘%’ for a
1386 percentage of the window size (for example ‘-x 10%’). With -Z,
1387 the active pane is toggled between zoomed (occupying the whole of
1388 the window) and unzoomed (its normal position in the layout).
1389 -M begins mouse resizing (only valid if bound to a mouse key
1391 binding, see MOUSE SUPPORT).
1392 -T trims all lines below the current cursor position and moves
1394 lines out of the history to replace them.
1395 resize-window [-aADLRU] [-t target-window] [-x width] [-y height]
1397 [adjustment]
1398 (alias: resizew)
1399 Resize a window, up, down, left or right by adjustment with -U,
1400 -D, -L or -R, or to an absolute size with -x or -y. The
1401 adjustment is given in lines or cells (the default is 1). -A
1402 sets the size of the largest session containing the window; -a
1403 the size of the smallest. This command will automatically set
1404 window-size to manual in the window options.
1405 respawn-pane [-k] [-c start-directory] [-e environment] [-t target-pane]
1407 [shell-command]
1408 (alias: respawnp)
1409 Reactivate a pane in which the command has exited (see the
1410 remain-on-exit window option). If shell-command is not given,
1411 the command used when the pane was created or last respawned is
1412 executed. The pane must be already inactive, unless -k is given,
1413 in which case any existing command is killed. -c specifies a new
1414 working directory for the pane. The -e option has the same mean‐
1415 ing as for the new-window command.
1416 respawn-window [-k] [-c start-directory] [-e environment] [-t
1418 target-window] [shell-command]
1419 (alias: respawnw)
1420 Reactivate a window in which the command has exited (see the
1421 remain-on-exit window option). If shell-command is not given,
1422 the command used when the window was created or last respawned is
1423 executed. The window must be already inactive, unless -k is
1424 given, in which case any existing command is killed. -c speci‐
1425 fies a new working directory for the window. The -e option has
1426 the same meaning as for the new-window command.
1427 rotate-window [-DUZ] [-t target-window]
1429 (alias: rotatew)
1430 Rotate the positions of the panes within a window, either upward
1431 (numerically lower) with -U or downward (numerically higher). -Z
1432 keeps the window zoomed if it was zoomed.
1433 select-layout [-Enop] [-t target-pane] [layout-name]
1435 (alias: selectl)
1436 Choose a specific layout for a window. If layout-name is not
1437 given, the last preset layout used (if any) is reapplied. -n and
1438 -p are equivalent to the next-layout and previous-layout com‐
1439 mands. -o applies the last set layout if possible (undoes the
1440 most recent layout change). -E spreads the current pane and any
1441 panes next to it out evenly.
1442 select-pane [-DdeLlMmRUZ] [-T title] [-t target-pane]
1444 (alias: selectp)
1445 Make pane target-pane the active pane in its window. If one of
1446 -D, -L, -R, or -U is used, respectively the pane below, to the
1447 left, to the right, or above the target pane is used. -Z keeps
1448 the window zoomed if it was zoomed. -l is the same as using the
1449 last-pane command. -e enables or -d disables input to the pane.
1450 -T sets the pane title.
1451 -m and -M are used to set and clear the marked pane. There is
1453 one marked pane at a time, setting a new marked pane clears the
1454 last. The marked pane is the default target for -s to join-pane,
1455 move-pane, swap-pane and swap-window.
1456 select-window [-lnpT] [-t target-window]
1458 (alias: selectw)
1459 Select the window at target-window. -l, -n and -p are equivalent
1460 to the last-window, next-window and previous-window commands. If
1461 -T is given and the selected window is already the current win‐
1462 dow, the command behaves like last-window.
1463 split-window [-bdfhIvPZ] [-c start-directory] [-e environment] [-l size]
1465 [-t target-pane] [shell-command] [-F format]
1466 (alias: splitw)
1467 Create a new pane by splitting target-pane: -h does a horizontal
1468 split and -v a vertical split; if neither is specified, -v is as‐
1469 sumed. The -l option specifies the size of the new pane in lines
1470 (for vertical split) or in columns (for horizontal split); size
1471 may be followed by ‘%’ to specify a percentage of the available
1472 space. The -b option causes the new pane to be created to the
1473 left of or above target-pane. The -f option creates a new pane
1474 spanning the full window height (with -h) or full window width
1475 (with -v), instead of splitting the active pane. -Z zooms if the
1476 window is not zoomed, or keeps it zoomed if already zoomed.
1477 An empty shell-command ('') will create a pane with no command
1479 running in it. Output can be sent to such a pane with the
1480 display-message command. The -I flag (if shell-command is not
1481 specified or empty) will create an empty pane and forward any
1482 output from stdin to it. For example:
1483 $ make 2>&1|tmux splitw -dI &
1485 All other options have the same meaning as for the new-window
1487 command.
1488 swap-pane [-dDUZ] [-s src-pane] [-t dst-pane]
1490 (alias: swapp)
1491 Swap two panes. If -U is used and no source pane is specified
1492 with -s, dst-pane is swapped with the previous pane (before it
1493 numerically); -D swaps with the next pane (after it numerically).
1494 -d instructs tmux not to change the active pane and -Z keeps the
1495 window zoomed if it was zoomed.
1496 If -s is omitted and a marked pane is present (see select-pane
1498 -m), the marked pane is used rather than the current pane.
1499 swap-window [-d] [-s src-window] [-t dst-window]
1501 (alias: swapw)
1502 This is similar to link-window, except the source and destination
1503 windows are swapped. It is an error if no window exists at
1504 src-window. If -d is given, the new window does not become the
1505 current window.
1506 If -s is omitted and a marked pane is present (see select-pane
1508 -m), the window containing the marked pane is used rather than
1509 the current window.
1510 unlink-window [-k] [-t target-window]
1512 (alias: unlinkw)
1513 Unlink target-window. Unless -k is given, a window may be un‐
1514 linked only if it is linked to multiple sessions - windows may
1515 not be linked to no sessions; if -k is specified and the window
1516 is linked to only one session, it is unlinked and destroyed.
1517
1519 tmux allows a command to be bound to most keys, with or without a prefix
1520 key. When specifying keys, most represent themselves (for example ‘A’ to
1521 ‘Z’). Ctrl keys may be prefixed with ‘C-’ or ‘^’, Shift keys with ‘S-’
1522 and Alt (meta) with ‘M-’. In addition, the following special key names
1523 are accepted: Up, Down, Left, Right, BSpace, BTab, DC (Delete), End,
1524 Enter, Escape, F1 to F12, Home, IC (Insert), NPage/PageDown/PgDn,
1525 PPage/PageUp/PgUp, Space, and Tab. Note that to bind the ‘"’ or ‘'’
1526 keys, quotation marks are necessary, for example:
1527 bind-key '"' split-window
1529 bind-key "'" new-window
1530 A command bound to the Any key will execute for all keys which do not
1532 have a more specific binding.
1533 Commands related to key bindings are as follows:
1535 bind-key [-nr] [-N note] [-T key-table] key command [arguments]
1537 (alias: bind)
1538 Bind key key to command. Keys are bound in a key table. By de‐
1539 fault (without -T), the key is bound in the prefix key table.
1540 This table is used for keys pressed after the prefix key (for ex‐
1541 ample, by default ‘c’ is bound to new-window in the prefix table,
1542 so ‘C-b c’ creates a new window). The root table is used for
1543 keys pressed without the prefix key: binding ‘c’ to new-window in
1544 the root table (not recommended) means a plain ‘c’ will create a
1545 new window. -n is an alias for -T root. Keys may also be bound
1546 in custom key tables and the switch-client -T command used to
1547 switch to them from a key binding. The -r flag indicates this
1548 key may repeat, see the repeat-time option. -N attaches a note
1549 to the key (shown with list-keys -N).
1550 To view the default bindings and possible commands, see the
1552 list-keys command.
1553 list-keys [-1aN] [-P prefix-string -T key-table] [key]
1555 (alias: lsk)
1556 List key bindings. There are two forms: the default lists keys
1557 as bind-key commands; -N lists only keys with attached notes and
1558 shows only the key and note for each key.
1559 With the default form, all key tables are listed by default. -T
1561 lists only keys in key-table.
1562 With the -N form, only keys in the root and prefix key tables are
1564 listed by default; -T also lists only keys in key-table. -P
1565 specifies a prefix to print before each key and -1 lists only the
1566 first matching key. -a lists the command for keys that do not
1567 have a note rather than skipping them.
1568 send-keys [-FHlMRX] [-N repeat-count] [-t target-pane] key ...
1570 (alias: send)
1571 Send a key or keys to a window. Each argument key is the name of
1572 the key (such as ‘C-a’ or ‘NPage’) to send; if the string is not
1573 recognised as a key, it is sent as a series of characters. All
1574 arguments are sent sequentially from first to last.
1575 The -l flag disables key name lookup and processes the keys as
1577 literal UTF-8 characters. The -H flag expects each key to be a
1578 hexadecimal number for an ASCII character.
1579 The -R flag causes the terminal state to be reset.
1581 -M passes through a mouse event (only valid if bound to a mouse
1583 key binding, see MOUSE SUPPORT).
1584 -X is used to send a command into copy mode - see the WINDOWS AND
1586 PANES section. -N specifies a repeat count and -F expands for‐
1587 mats in arguments where appropriate.
1588 send-prefix [-2] [-t target-pane]
1590 Send the prefix key, or with -2 the secondary prefix key, to a
1591 window as if it was pressed.
1592 unbind-key [-anq] [-T key-table] key
1594 (alias: unbind)
1595 Unbind the command bound to key. -n and -T are the same as for
1596 bind-key. If -a is present, all key bindings are removed. The
1597 -q option prevents errors being returned.
1598
1600 The appearance and behaviour of tmux may be modified by changing the
1601 value of various options. There are four types of option: server
1602 options, session options, window options, and pane options.
1603 The tmux server has a set of global server options which do not apply to
1605 any particular window or session or pane. These are altered with the
1606 set-option -s command, or displayed with the show-options -s command.
1607 In addition, each individual session may have a set of session options,
1609 and there is a separate set of global session options. Sessions which do
1610 not have a particular option configured inherit the value from the global
1611 session options. Session options are set or unset with the set-option
1612 command and may be listed with the show-options command. The available
1613 server and session options are listed under the set-option command.
1614 Similarly, a set of window options is attached to each window and a set
1616 of pane options to each pane. Pane options inherit from window options.
1617 This means any pane option may be set as a window option to apply the op‐
1618 tion to all panes in the window without the option set, for example these
1619 commands will set the background colour to red for all panes except pane
1620 0:
1621 set -w window-style bg=red
1623 set -pt:.0 window-style bg=blue
1624 There is also a set of global window options from which any unset window
1626 or pane options are inherited. Window and pane options are altered with
1627 set-option -w and -p commands and displayed with show-option -w and -p.
1628 tmux also supports user options which are prefixed with a ‘@’. User op‐
1630 tions may have any name, so long as they are prefixed with ‘@’, and be
1631 set to any string. For example:
1632 $ tmux set -wq @foo "abc123"
1634 $ tmux show -wv @foo
1635 abc123
1636 Commands which set options are as follows:
1638 set-option [-aFgopqsuUw] [-t target-pane] option value
1640 (alias: set)
1641 Set a pane option with -p, a window option with -w, a server op‐
1642 tion with -s, otherwise a session option. If the option is not a
1643 user option, -w or -s may be unnecessary - tmux will infer the
1644 type from the option name, assuming -w for pane options. If -g
1645 is given, the global session or window option is set.
1646 -F expands formats in the option value. The -u flag unsets an
1648 option, so a session inherits the option from the global options
1649 (or with -g, restores a global option to the default). -U unsets
1650 an option (like -u) but if the option is a pane option also un‐
1651 sets the option on any panes in the window. value depends on the
1652 option and may be a number, a string, or a flag (on, off, or
1653 omitted to toggle).
1654 The -o flag prevents setting an option that is already set and
1656 the -q flag suppresses errors about unknown or ambiguous options.
1657 With -a, and if the option expects a string or a style, value is
1659 appended to the existing setting. For example:
1660 set -g status-left "foo"
1662 set -ag status-left "bar"
1663 Will result in ‘foobar’. And:
1665 set -g status-style "bg=red"
1667 set -ag status-style "fg=blue"
1668 Will result in a red background and blue foreground. Without -a,
1670 the result would be the default background and a blue foreground.
1671 show-options [-AgHpqsvw] [-t target-pane] [option]
1673 (alias: show)
1674 Show the pane options (or a single option if option is provided)
1675 with -p, the window options with -w, the server options with -s,
1676 otherwise the session options. If the option is not a user op‐
1677 tion, -w or -s may be unnecessary - tmux will infer the type from
1678 the option name, assuming -w for pane options. Global session or
1679 window options are listed if -g is used. -v shows only the op‐
1680 tion value, not the name. If -q is set, no error will be re‐
1681 turned if option is unset. -H includes hooks (omitted by de‐
1682 fault). -A includes options inherited from a parent set of op‐
1683 tions, such options are marked with an asterisk.
1684 Available server options are:
1686 backspace key
1688 Set the key sent by tmux for backspace.
1689 buffer-limit number
1691 Set the number of buffers; as new buffers are added to the top of
1692 the stack, old ones are removed from the bottom if necessary to
1693 maintain this maximum length.
1694 command-alias[] name=value
1696 This is an array of custom aliases for commands. If an unknown
1697 command matches name, it is replaced with value. For example,
1698 after:
1699 set -s command-alias[100] zoom='resize-pane -Z'
1701 Using:
1703 zoom -t:.1
1705 Is equivalent to:
1707 resize-pane -Z -t:.1
1709 Note that aliases are expanded when a command is parsed rather
1711 than when it is executed, so binding an alias with bind-key will
1712 bind the expanded form.
1713 default-terminal terminal
1715 Set the default terminal for new windows created in this session
1716 - the default value of the TERM environment variable. For tmux
1717 to work correctly, this must be set to ‘screen’, ‘tmux’ or a de‐
1718 rivative of them.
1719 copy-command shell-command
1721 Give the command to pipe to if the copy-pipe copy mode command is
1722 used without arguments.
1723 escape-time time
1725 Set the time in milliseconds for which tmux waits after an escape
1726 is input to determine if it is part of a function or meta key se‐
1727 quences. The default is 500 milliseconds.
1728 editor shell-command
1730 Set the command used when tmux runs an editor.
1731 exit-empty [on | off]
1733 If enabled (the default), the server will exit when there are no
1734 active sessions.
1735 exit-unattached [on | off]
1737 If enabled, the server will exit when there are no attached
1738 clients.
1739 extended-keys [on | off | always]
1741 When on or always, the escape sequence to enable extended keys is
1742 sent to the terminal, if tmux knows that it is supported. tmux
1743 always recognises extended keys itself. If this option is on,
1744 tmux will only forward extended keys to applications when they
1745 request them; if always, tmux will always forward the keys.
1746 focus-events [on | off]
1748 When enabled, focus events are requested from the terminal if
1749 supported and passed through to applications running in tmux.
1750 Attached clients should be detached and attached again after
1751 changing this option.
1752 history-file path
1754 If not empty, a file to which tmux will write command prompt his‐
1755 tory on exit and load it from on start.
1756 message-limit number
1758 Set the number of error or information messages to save in the
1759 message log for each client. The default is 100.
1760 set-clipboard [on | external | off]
1762 Attempt to set the terminal clipboard content using the xterm(1)
1763 escape sequence, if there is an Ms entry in the terminfo(5) de‐
1764 scription (see the TERMINFO EXTENSIONS section).
1765 If set to on, tmux will both accept the escape sequence to create
1767 a buffer and attempt to set the terminal clipboard. If set to
1768 external, tmux will attempt to set the terminal clipboard but ig‐
1769 nore attempts by applications to set tmux buffers. If off, tmux
1770 will neither accept the clipboard escape sequence nor attempt to
1771 set the clipboard.
1772 Note that this feature needs to be enabled in xterm(1) by setting
1774 the resource:
1775 disallowedWindowOps: 20,21,SetXprop
1777 Or changing this property from the xterm(1) interactive menu when
1779 required.
1780 terminal-features[] string
1782 Set terminal features for terminal types read from terminfo(5).
1783 tmux has a set of named terminal features. Each will apply ap‐
1784 propriate changes to the terminfo(5) entry in use.
1785 tmux can detect features for a few common terminals; this option
1787 can be used to easily tell tmux about features supported by ter‐
1788 minals it cannot detect. The terminal-overrides option allows
1789 individual terminfo(5) capabilities to be set instead,
1790 terminal-features is intended for classes of functionality sup‐
1791 ported in a standard way but not reported by terminfo(5). Care
1792 must be taken to configure this only with features the terminal
1793 actually supports.
1794 This is an array option where each entry is a colon-separated
1796 string made up of a terminal type pattern (matched using
1797 fnmatch(3)) followed by a list of terminal features. The avail‐
1798 able features are:
1799 256 Supports 256 colours with the SGR escape sequences.
1801 clipboard
1803 Allows setting the system clipboard.
1804 ccolour
1806 Allows setting the cursor colour.
1807 cstyle Allows setting the cursor style.
1809 extkeys
1811 Supports extended keys.
1812 focus Supports focus reporting.
1814 margins
1816 Supports DECSLRM margins.
1817 mouse Supports xterm(1) mouse sequences.
1819 overline
1821 Supports the overline SGR attribute.
1822 rectfill
1824 Supports the DECFRA rectangle fill escape sequence.
1825 RGB Supports RGB colour with the SGR escape sequences.
1827 strikethrough
1829 Supports the strikethrough SGR escape sequence.
1830 sync Supports synchronized updates.
1832 title Supports xterm(1) title setting.
1834 usstyle
1836 Allows underscore style and colour to be set.
1837 terminal-overrides[] string
1839 Allow terminal descriptions read using terminfo(5) to be overrid‐
1840 den. Each entry is a colon-separated string made up of a termi‐
1841 nal type pattern (matched using fnmatch(3)) and a set of
1842 name=value entries.
1843 For example, to set the ‘clear’ terminfo(5) entry to ‘\e[H\e[2J’
1845 for all terminal types matching ‘rxvt*’:
1846 rxvt*:clear=\e[H\e[2J
1848 The terminal entry value is passed through strunvis(3) before in‐
1850 terpretation.
1851 user-keys[] key
1853 Set list of user-defined key escape sequences. Each item is as‐
1854 sociated with a key named ‘User0’, ‘User1’, and so on.
1855 For example:
1857 set -s user-keys[0] "\e[5;30012~"
1859 bind User0 resize-pane -L 3
1860 Available session options are:
1862 activity-action [any | none | current | other]
1864 Set action on window activity when monitor-activity is on. any
1865 means activity in any window linked to a session causes a bell or
1866 message (depending on visual-activity) in the current window of
1867 that session, none means all activity is ignored (equivalent to
1868 monitor-activity being off), current means only activity in win‐
1869 dows other than the current window are ignored and other means
1870 activity in the current window is ignored but not those in other
1871 windows.
1872 assume-paste-time milliseconds
1874 If keys are entered faster than one in milliseconds, they are as‐
1875 sumed to have been pasted rather than typed and tmux key bindings
1876 are not processed. The default is one millisecond and zero dis‐
1877 ables.
1878 base-index index
1880 Set the base index from which an unused index should be searched
1881 when a new window is created. The default is zero.
1882 bell-action [any | none | current | other]
1884 Set action on a bell in a window when monitor-bell is on. The
1885 values are the same as those for activity-action.
1886 default-command shell-command
1888 Set the command used for new windows (if not specified when the
1889 window is created) to shell-command, which may be any sh(1) com‐
1890 mand. The default is an empty string, which instructs tmux to
1891 create a login shell using the value of the default-shell option.
1892 default-shell path
1894 Specify the default shell. This is used as the login shell for
1895 new windows when the default-command option is set to empty, and
1896 must be the full path of the executable. When started tmux tries
1897 to set a default value from the first suitable of the SHELL envi‐
1898 ronment variable, the shell returned by getpwuid(3), or /bin/sh.
1899 This option should be configured when tmux is used as a login
1900 shell.
1901 default-size XxY
1903 Set the default size of new windows when the window-size option
1904 is set to manual or when a session is created with new-session
1905 -d. The value is the width and height separated by an ‘x’ char‐
1906 acter. The default is 80x24.
1907 destroy-unattached [on | off]
1909 If enabled and the session is no longer attached to any clients,
1910 it is destroyed.
1911 detach-on-destroy [off | on | no-detached]
1913 If on (the default), the client is detached when the session it
1914 is attached to is destroyed. If off, the client is switched to
1915 the most recently active of the remaining sessions. If
1916 no-detached, the client is detached only if there are no detached
1917 sessions; if detached sessions exist, the client is switched to
1918 the most recently active.
1919 display-panes-active-colour colour
1921 Set the colour used by the display-panes command to show the in‐
1922 dicator for the active pane.
1923 display-panes-colour colour
1925 Set the colour used by the display-panes command to show the in‐
1926 dicators for inactive panes.
1927 display-panes-time time
1929 Set the time in milliseconds for which the indicators shown by
1930 the display-panes command appear.
1931 display-time time
1933 Set the amount of time for which status line messages and other
1934 on-screen indicators are displayed. If set to 0, messages and
1935 indicators are displayed until a key is pressed. time is in mil‐
1936 liseconds.
1937 history-limit lines
1939 Set the maximum number of lines held in window history. This
1940 setting applies only to new windows - existing window histories
1941 are not resized and retain the limit at the point they were cre‐
1942 ated.
1943 key-table key-table
1945 Set the default key table to key-table instead of root.
1946 lock-after-time number
1948 Lock the session (like the lock-session command) after number
1949 seconds of inactivity. The default is not to lock (set to 0).
1950 lock-command shell-command
1952 Command to run when locking each client. The default is to run
1953 lock(1) with -np.
1954 message-command-style style
1956 Set status line message command style. This is used for the com‐
1957 mand prompt with vi(1) keys when in command mode. For how to
1958 specify style, see the STYLES section.
1959 message-style style
1961 Set status line message style. This is used for messages and for
1962 the command prompt. For how to specify style, see the STYLES
1963 section.
1964 mouse [on | off]
1966 If on, tmux captures the mouse and allows mouse events to be
1967 bound as key bindings. See the MOUSE SUPPORT section for de‐
1968 tails.
1969 prefix key
1971 Set the key accepted as a prefix key. In addition to the stan‐
1972 dard keys described under KEY BINDINGS, prefix can be set to the
1973 special key ‘None’ to set no prefix.
1974 prefix2 key
1976 Set a secondary key accepted as a prefix key. Like prefix,
1977 prefix2 can be set to ‘None’.
1978 renumber-windows [on | off]
1980 If on, when a window is closed in a session, automatically renum‐
1981 ber the other windows in numerical order. This respects the
1982 base-index option if it has been set. If off, do not renumber
1983 the windows.
1984 repeat-time time
1986 Allow multiple commands to be entered without pressing the pre‐
1987 fix-key again in the specified time milliseconds (the default is
1988 500). Whether a key repeats may be set when it is bound using
1989 the -r flag to bind-key. Repeat is enabled for the default keys
1990 bound to the resize-pane command.
1991 set-titles [on | off]
1993 Attempt to set the client terminal title using the tsl and fsl
1994 terminfo(5) entries if they exist. tmux automatically sets these
1995 to the \e]0;...\007 sequence if the terminal appears to be
1996 xterm(1). This option is off by default.
1997 set-titles-string string
1999 String used to set the client terminal title if set-titles is on.
2000 Formats are expanded, see the FORMATS section.
2001 silence-action [any | none | current | other]
2003 Set action on window silence when monitor-silence is on. The
2004 values are the same as those for activity-action.
2005 status [off | on | 2 | 3 | 4 | 5]
2007 Show or hide the status line or specify its size. Using on gives
2008 a status line one row in height; 2, 3, 4 or 5 more rows.
2009 status-format[] format
2011 Specify the format to be used for each line of the status line.
2012 The default builds the top status line from the various individ‐
2013 ual status options below.
2014 status-interval interval
2016 Update the status line every interval seconds. By default, up‐
2017 dates will occur every 15 seconds. A setting of zero disables
2018 redrawing at interval.
2019 status-justify [left | centre | right | absolute-centre]
2021 Set the position of the window list in the status line: left,
2022 centre or right. centre puts the window list in the relative
2023 centre of the available free space; absolute-centre uses the cen‐
2024 tre of the entire horizontal space.
2025 status-keys [vi | emacs]
2027 Use vi or emacs-style key bindings in the status line, for exam‐
2028 ple at the command prompt. The default is emacs, unless the
2029 VISUAL or EDITOR environment variables are set and contain the
2030 string ‘vi’.
2031 status-left string
2033 Display string (by default the session name) to the left of the
2034 status line. string will be passed through strftime(3). Also
2035 see the FORMATS and STYLES sections.
2036 For details on how the names and titles can be set see the NAMES
2038 AND TITLES section.
2039 Examples are:
2041 #(sysctl vm.loadavg)
2043 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
2044 The default is ‘[#S] ’.
2046 status-left-length length
2048 Set the maximum length of the left component of the status line.
2049 The default is 10.
2050 status-left-style style
2052 Set the style of the left part of the status line. For how to
2053 specify style, see the STYLES section.
2054 status-position [top | bottom]
2056 Set the position of the status line.
2057 status-right string
2059 Display string to the right of the status line. By default, the
2060 current pane title in double quotes, the date and the time are
2061 shown. As with status-left, string will be passed to strftime(3)
2062 and character pairs are replaced.
2063 status-right-length length
2065 Set the maximum length of the right component of the status line.
2066 The default is 40.
2067 status-right-style style
2069 Set the style of the right part of the status line. For how to
2070 specify style, see the STYLES section.
2071 status-style style
2073 Set status line style. For how to specify style, see the STYLES
2074 section.
2075 update-environment[] variable
2077 Set list of environment variables to be copied into the session
2078 environment when a new session is created or an existing session
2079 is attached. Any variables that do not exist in the source envi‐
2080 ronment are set to be removed from the session environment (as if
2081 -r was given to the set-environment command).
2082 visual-activity [on | off | both]
2084 If on, display a message instead of sending a bell when activity
2085 occurs in a window for which the monitor-activity window option
2086 is enabled. If set to both, a bell and a message are produced.
2087 visual-bell [on | off | both]
2089 If on, a message is shown on a bell in a window for which the
2090 monitor-bell window option is enabled instead of it being passed
2091 through to the terminal (which normally makes a sound). If set
2092 to both, a bell and a message are produced. Also see the
2093 bell-action option.
2094 visual-silence [on | off | both]
2096 If monitor-silence is enabled, prints a message after the inter‐
2097 val has expired on a given window instead of sending a bell. If
2098 set to both, a bell and a message are produced.
2099 word-separators string
2101 Sets the session's conception of what characters are considered
2102 word separators, for the purposes of the next and previous word
2103 commands in copy mode. The default is ‘ -_@’.
2104 Available window options are:
2106 aggressive-resize [on | off]
2108 Aggressively resize the chosen window. This means that tmux will
2109 resize the window to the size of the smallest or largest session
2110 (see the window-size option) for which it is the current window,
2111 rather than the session to which it is attached. The window may
2112 resize when the current window is changed on another session;
2113 this option is good for full-screen programs which support
2114 SIGWINCH and poor for interactive programs such as shells.
2115 automatic-rename [on | off]
2117 Control automatic window renaming. When this setting is enabled,
2118 tmux will rename the window automatically using the format speci‐
2119 fied by automatic-rename-format. This flag is automatically dis‐
2120 abled for an individual window when a name is specified at cre‐
2121 ation with new-window or new-session, or later with
2122 rename-window, or with a terminal escape sequence. It may be
2123 switched off globally with:
2124 set-option -wg automatic-rename off
2126 automatic-rename-format format
2128 The format (see FORMATS) used when the automatic-rename option is
2129 enabled.
2130 clock-mode-colour colour
2132 Set clock colour.
2133 clock-mode-style [12 | 24]
2135 Set clock hour format.
2136 main-pane-height height
2138 main-pane-width width
2139 Set the width or height of the main (left or top) pane in the
2140 main-horizontal or main-vertical layouts. If suffixed by ‘%’,
2141 this is a percentage of the window size.
2142 copy-mode-match-style style
2144 Set the style of search matches in copy mode. For how to specify
2145 style, see the STYLES section.
2146 copy-mode-mark-style style
2148 Set the style of the line containing the mark in copy mode. For
2149 how to specify style, see the STYLES section.
2150 copy-mode-current-match-style style
2152 Set the style of the current search match in copy mode. For how
2153 to specify style, see the STYLES section.
2154 mode-keys [vi | emacs]
2156 Use vi or emacs-style key bindings in copy mode. The default is
2157 emacs, unless VISUAL or EDITOR contains ‘vi’.
2158 mode-style style
2160 Set window modes style. For how to specify style, see the STYLES
2161 section.
2162 monitor-activity [on | off]
2164 Monitor for activity in the window. Windows with activity are
2165 highlighted in the status line.
2166 monitor-bell [on | off]
2168 Monitor for a bell in the window. Windows with a bell are high‐
2169 lighted in the status line.
2170 monitor-silence [interval]
2172 Monitor for silence (no activity) in the window within interval
2173 seconds. Windows that have been silent for the interval are
2174 highlighted in the status line. An interval of zero disables the
2175 monitoring.
2176 other-pane-height height
2178 Set the height of the other panes (not the main pane) in the
2179 main-horizontal layout. If this option is set to 0 (the de‐
2180 fault), it will have no effect. If both the main-pane-height and
2181 other-pane-height options are set, the main pane will grow taller
2182 to make the other panes the specified height, but will never
2183 shrink to do so. If suffixed by ‘%’, this is a percentage of the
2184 window size.
2185 other-pane-width width
2187 Like other-pane-height, but set the width of other panes in the
2188 main-vertical layout.
2189 pane-active-border-style style
2191 Set the pane border style for the currently active pane. For how
2192 to specify style, see the STYLES section. Attributes are ig‐
2193 nored.
2194 pane-base-index index
2196 Like base-index, but set the starting index for pane numbers.
2197 pane-border-format format
2199 Set the text shown in pane border status lines.
2200 pane-border-lines type
2202 Set the type of characters used for drawing pane borders. type
2203 may be one of:
2204 single single lines using ACS or UTF-8 characters
2206 double double lines using UTF-8 characters
2208 heavy heavy lines using UTF-8 characters
2210 simple simple ASCII characters
2212 number the pane number
2214 ‘double’ and ‘heavy’ will fall back to standard ACS line drawing
2216 when UTF-8 is not supported.
2217 pane-border-status [off | top | bottom]
2219 Turn pane border status lines off or set their position.
2220 pane-border-style style
2222 Set the pane border style for panes aside from the active pane.
2223 For how to specify style, see the STYLES section. Attributes are
2224 ignored.
2225 window-status-activity-style style
2227 Set status line style for windows with an activity alert. For
2228 how to specify style, see the STYLES section.
2229 window-status-bell-style style
2231 Set status line style for windows with a bell alert. For how to
2232 specify style, see the STYLES section.
2233 window-status-current-format string
2235 Like window-status-format, but is the format used when the window
2236 is the current window.
2237 window-status-current-style style
2239 Set status line style for the currently active window. For how
2240 to specify style, see the STYLES section.
2241 window-status-format string
2243 Set the format in which the window is displayed in the status
2244 line window list. See the FORMATS and STYLES sections.
2245 window-status-last-style style
2247 Set status line style for the last active window. For how to
2248 specify style, see the STYLES section.
2249 window-status-separator string
2251 Sets the separator drawn between windows in the status line. The
2252 default is a single space character.
2253 window-status-style style
2255 Set status line style for a single window. For how to specify
2256 style, see the STYLES section.
2257 window-size largest | smallest | manual | latest
2259 Configure how tmux determines the window size. If set to
2260 largest, the size of the largest attached session is used; if
2261 smallest, the size of the smallest. If manual, the size of a new
2262 window is set from the default-size option and windows are re‐
2263 sized automatically. With latest, tmux uses the size of the
2264 client that had the most recent activity. See also the
2265 resize-window command and the aggressive-resize option.
2266 wrap-search [on | off]
2268 If this option is set, searches will wrap around the end of the
2269 pane contents. The default is on.
2270 Available pane options are:
2272 allow-rename [on | off]
2274 Allow programs in the pane to change the window name using a ter‐
2275 minal escape sequence (\ek...\e\\).
2276 alternate-screen [on | off]
2278 This option configures whether programs running inside the pane
2279 may use the terminal alternate screen feature, which allows the
2280 smcup and rmcup terminfo(5) capabilities. The alternate screen
2281 feature preserves the contents of the window when an interactive
2282 application starts and restores it on exit, so that any output
2283 visible before the application starts reappears unchanged after
2284 it exits.
2285 remain-on-exit [on | off | failed]
2287 A pane with this flag set is not destroyed when the program run‐
2288 ning in it exits. If set to failed, then only when the program
2289 exit status is not zero. The pane may be reactivated with the
2290 respawn-pane command.
2291 synchronize-panes [on | off]
2293 Duplicate input to all other panes in the same window where this
2294 option is also on (only for panes that are not in any mode).
2295 window-active-style style
2297 Set the pane style when it is the active pane. For how to spec‐
2298 ify style, see the STYLES section.
2299 window-style style
2301 Set the pane style. For how to specify style, see the STYLES
2302 section.
2303
2305 tmux allows commands to run on various triggers, called hooks. Most tmux
2306 commands have an after hook and there are a number of hooks not associ‐
2307 ated with commands.
2308 Hooks are stored as array options, members of the array are executed in
2310 order when the hook is triggered. Like options different hooks may be
2311 global or belong to a session, window or pane. Hooks may be configured
2312 with the set-hook or set-option commands and displayed with show-hooks or
2313 show-options -H. The following two commands are equivalent:
2314 set-hook -g pane-mode-changed[42] 'set -g status-left-style bg=red'
2316 set-option -g pane-mode-changed[42] 'set -g status-left-style bg=red'
2317 Setting a hook without specifying an array index clears the hook and sets
2319 the first member of the array.
2320 A command's after hook is run after it completes, except when the command
2322 is run as part of a hook itself. They are named with an ‘after-’ prefix.
2323 For example, the following command adds a hook to select the even-verti‐
2324 cal layout after every split-window:
2325 set-hook -g after-split-window "selectl even-vertical"
2327 All the notifications listed in the CONTROL MODE section are hooks (with‐
2329 out any arguments), except %exit. The following additional hooks are
2330 available:
2331 alert-activity Run when a window has activity. See
2333 monitor-activity.
2334 alert-bell Run when a window has received a bell. See
2336 monitor-bell.
2337 alert-silence Run when a window has been silent. See
2339 monitor-silence.
2340 client-attached Run when a client is attached.
2342 client-detached Run when a client is detached
2344 client-resized Run when a client is resized.
2346 client-session-changed Run when a client's attached session is changed.
2348 pane-died Run when the program running in a pane exits, but
2350 remain-on-exit is on so the pane has not closed.
2351 pane-exited Run when the program running in a pane exits.
2353 pane-focus-in Run when the focus enters a pane, if the
2355 focus-events option is on.
2356 pane-focus-out Run when the focus exits a pane, if the
2358 focus-events option is on.
2359 pane-set-clipboard Run when the terminal clipboard is set using the
2361 xterm(1) escape sequence.
2362 session-created Run when a new session created.
2364 session-closed Run when a session closed.
2366 session-renamed Run when a session is renamed.
2368 window-linked Run when a window is linked into a session.
2370 window-renamed Run when a window is renamed.
2372 window-unlinked Run when a window is unlinked from a session.
2374 Hooks are managed with these commands:
2376 set-hook [-agpRuw] [-t target-pane] hook-name command
2378 Without -R, sets (or with -u unsets) hook hook-name to command.
2379 The flags are the same as for set-option.
2380 With -R, run hook-name immediately.
2382 show-hooks [-gpw] [-t target-pane]
2384 Shows hooks. The flags are the same as for show-options.
2385
2387 If the mouse option is on (the default is off), tmux allows mouse events
2388 to be bound as keys. The name of each key is made up of a mouse event
2389 (such as ‘MouseUp1’) and a location suffix, one of the following:
2390 Pane the contents of a pane
2392 Border a pane border
2393 Status the status line window list
2394 StatusLeft the left part of the status line
2395 StatusRight the right part of the status line
2396 StatusDefault any other part of the status line
2397 The following mouse events are available:
2399 WheelUp WheelDown
2401 MouseDown1 MouseUp1 MouseDrag1 MouseDragEnd1
2402 MouseDown2 MouseUp2 MouseDrag2 MouseDragEnd2
2403 MouseDown3 MouseUp3 MouseDrag3 MouseDragEnd3
2404 SecondClick1 SecondClick2 SecondClick3
2405 DoubleClick1 DoubleClick2 DoubleClick3
2406 TripleClick1 TripleClick2 TripleClick3
2407 The ‘SecondClick’ events are fired for the second click of a double
2409 click, even if there may be a third click which will fire ‘TripleClick’
2410 instead of ‘DoubleClick’.
2411 Each should be suffixed with a location, for example ‘MouseDown1Status’.
2413 The special token ‘{mouse}’ or ‘=’ may be used as target-window or
2415 target-pane in commands bound to mouse key bindings. It resolves to the
2416 window or pane over which the mouse event took place (for example, the
2417 window in the status line over which button 1 was released for a
2418 ‘MouseUp1Status’ binding, or the pane over which the wheel was scrolled
2419 for a ‘WheelDownPane’ binding).
2420 The send-keys -M flag may be used to forward a mouse event to a pane.
2422 The default key bindings allow the mouse to be used to select and resize
2424 panes, to copy text and to change window using the status line. These
2425 take effect if the mouse option is turned on.
2426
2428 Certain commands accept the -F flag with a format argument. This is a
2429 string which controls the output format of the command. Format variables
2430 are enclosed in ‘#{’ and ‘}’, for example ‘#{session_name}’. The possi‐
2431 ble variables are listed in the table below, or the name of a tmux option
2432 may be used for an option's value. Some variables have a shorter alias
2433 such as ‘#S’; ‘##’ is replaced by a single ‘#’, ‘#,’ by a ‘,’ and ‘#}’ by
2434 a ‘}’.
2435 Conditionals are available by prefixing with ‘?’ and separating two al‐
2437 ternatives with a comma; if the specified variable exists and is not
2438 zero, the first alternative is chosen, otherwise the second is used. For
2439 example ‘#{?session_attached,attached,not attached}’ will include the
2440 string ‘attached’ if the session is attached and the string ‘not
2441 attached’ if it is unattached, or ‘#{?automatic-rename,yes,no}’ will in‐
2442 clude ‘yes’ if automatic-rename is enabled, or ‘no’ if not. Conditionals
2443 can be nested arbitrarily. Inside a conditional, ‘,’ and ‘}’ must be es‐
2444 caped as ‘#,’ and ‘#}’, unless they are part of a ‘#{...}’ replacement.
2445 For example:
2446 #{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W .
2448 String comparisons may be expressed by prefixing two comma-separated al‐
2450 ternatives by ‘==’, ‘!=’, ‘<’, ‘>’, ‘<=’ or ‘>=’ and a colon. For exam‐
2451 ple ‘#{==:#{host},myhost}’ will be replaced by ‘1’ if running on
2452 ‘myhost’, otherwise by ‘0’. ‘||’ and ‘&&’ evaluate to true if either or
2453 both of two comma-separated alternatives are true, for example
2454 ‘#{||:#{pane_in_mode},#{alternate_on}}’.
2455 An ‘m’ specifies an fnmatch(3) or regular expression comparison. The
2457 first argument is the pattern and the second the string to compare. An
2458 optional argument specifies flags: ‘r’ means the pattern is a regular ex‐
2459 pression instead of the default fnmatch(3) pattern, and ‘i’ means to ig‐
2460 nore case. For example: ‘#{m:*foo*,#{host}}’ or ‘#{m/ri:^A,MYVAR}’. A
2461 ‘C’ performs a search for an fnmatch(3) pattern or regular expression in
2462 the pane content and evaluates to zero if not found, or a line number if
2463 found. Like ‘m’, an ‘r’ flag means search for a regular expression and
2464 ‘i’ ignores case. For example: ‘#{C/r:^Start}’
2465 Numeric operators may be performed by prefixing two comma-separated al‐
2467 ternatives with an ‘e’ and an operator. An optional ‘f’ flag may be
2468 given after the operator to use floating point numbers, otherwise inte‐
2469 gers are used. This may be followed by a number giving the number of
2470 decimal places to use for the result. The available operators are: addi‐
2471 tion ‘+’, subtraction ‘-’, multiplication ‘*’, division ‘/’, modulus ‘m’
2472 or ‘%’ (note that ‘%’ must be escaped as ‘%%’ in formats which are also
2473 expanded by strftime(3)) and numeric comparison operators ‘==’, ‘!=’,
2474 ‘<’, ‘<=’, ‘>’ and ‘>=’. For example, ‘#{e|*|f|4:5.5,3}’ multiplies 5.5
2475 by 3 for a result with four decimal places and ‘#{e|%%:7,3}’ returns the
2476 modulus of 7 and 3. ‘a’ replaces a numeric argument by its ASCII equiva‐
2477 lent, so ‘#{a:98}’ results in ‘b’.
2478 A limit may be placed on the length of the resultant string by prefixing
2480 it by an ‘=’, a number and a colon. Positive numbers count from the
2481 start of the string and negative from the end, so ‘#{=5:pane_title}’ will
2482 include at most the first five characters of the pane title, or
2483 ‘#{=-5:pane_title}’ the last five characters. A suffix or prefix may be
2484 given as a second argument - if provided then it is appended or prepended
2485 to the string if the length has been trimmed, for example
2486 ‘#{=/5/...:pane_title}’ will append ‘...’ if the pane title is more than
2487 five characters. Similarly, ‘p’ pads the string to a given width, for
2488 example ‘#{p10:pane_title}’ will result in a width of at least 10 charac‐
2489 ters. A positive width pads on the left, a negative on the right. ‘n’
2490 expands to the length of the variable and ‘w’ to its width when dis‐
2491 played, for example ‘#{n:window_name}’.
2492 Prefixing a time variable with ‘t:’ will convert it to a string, so if
2494 ‘#{window_activity}’ gives ‘1445765102’, ‘#{t:window_activity}’ gives
2495 ‘Sun Oct 25 09:25:02 2015’. Adding ‘p (’ ‘`t/p`’) will use shorter but
2496 less accurate time format for times in the past. A custom format may be
2497 given using an ‘f’ suffix (note that ‘%’ must be escaped as ‘%%’ if the
2498 format is separately being passed through strftime(3), for example in the
2499 status-left option): ‘#{t/f/%%H#:%%M:window_activity}’, see strftime(3).
2500 The ‘b:’ and ‘d:’ prefixes are basename(3) and dirname(3) of the variable
2502 respectively. ‘q:’ will escape sh(1) special characters or with a ‘h’
2503 suffix, escape hash characters (so ‘#’ becomes ‘##’). ‘E:’ will expand
2504 the format twice, for example ‘#{E:status-left}’ is the result of expand‐
2505 ing the content of the status-left option rather than the option itself.
2506 ‘T:’ is like ‘E:’ but also expands strftime(3) specifiers. ‘S:’, ‘W:’ or
2507 ‘P:’ will loop over each session, window or pane and insert the format
2508 once for each. For windows and panes, two comma-separated formats may be
2509 given: the second is used for the current window or active pane. For ex‐
2510 ample, to get a list of windows formatted like the status line:
2511 #{W:#{E:window-status-format} ,#{E:window-status-current-format} }
2513 ‘N:’ checks if a window (without any suffix or with the ‘w’ suffix) or a
2515 session (with the ‘s’ suffix) name exists, for example ‘`N/w:foo`’ is re‐
2516 placed with 1 if a window named ‘foo’ exists.
2517 A prefix of the form ‘s/foo/bar/:’ will substitute ‘foo’ with ‘bar’
2519 throughout. The first argument may be an extended regular expression and
2520 a final argument may be ‘i’ to ignore case, for example ‘s/a(.)/\1x/i:’
2521 would change ‘abABab’ into ‘bxBxbx’.
2522 In addition, the last line of a shell command's output may be inserted
2524 using ‘#()’. For example, ‘#(uptime)’ will insert the system's uptime.
2525 When constructing formats, tmux does not wait for ‘#()’ commands to fin‐
2526 ish; instead, the previous result from running the same command is used,
2527 or a placeholder if the command has not been run before. If the command
2528 hasn't exited, the most recent line of output will be used, but the sta‐
2529 tus line will not be updated more than once a second. Commands are exe‐
2530 cuted with the tmux global environment set (see the GLOBAL AND SESSION
2531 ENVIRONMENT section).
2532 An ‘l’ specifies that a string should be interpreted literally and not
2534 expanded. For example ‘#{l:#{?pane_in_mode,yes,no}}’ will be replaced by
2535 ‘#{?pane_in_mode,yes,no}’.
2536 The following variables are available, where appropriate:
2538 Variable name Alias Replaced with
2540 active_window_index Index of active window in session
2541 alternate_on 1 if pane is in alternate screen
2542 alternate_saved_x Saved cursor X in alternate screen
2543 alternate_saved_y Saved cursor Y in alternate screen
2544 buffer_created Time buffer created
2545 buffer_name Name of buffer
2546 buffer_sample Sample of start of buffer
2547 buffer_size Size of the specified buffer in bytes
2548 client_activity Time client last had activity
2549 client_cell_height Height of each client cell in pixels
2550 client_cell_width Width of each client cell in pixels
2551 client_control_mode 1 if client is in control mode
2552 client_created Time client created
2553 client_discarded Bytes discarded when client behind
2554 client_flags List of client flags
2555 client_height Height of client
2556 client_key_table Current key table
2557 client_last_session Name of the client's last session
2558 client_name Name of client
2559 client_pid PID of client process
2560 client_prefix 1 if prefix key has been pressed
2561 client_readonly 1 if client is readonly
2562 client_session Name of the client's session
2563 client_termfeatures Terminal features of client, if any
2564 client_termname Terminal name of client
2565 client_termtype Terminal type of client, if available
2566 client_tty Pseudo terminal of client
2567 client_utf8 1 if client supports UTF-8
2568 client_width Width of client
2569 client_written Bytes written to client
2570 command Name of command in use, if any
2571 command_list_alias Command alias if listing commands
2572 command_list_name Command name if listing commands
2573 command_list_usage Command usage if listing commands
2574 config_files List of configuration files loaded
2575 copy_cursor_line Line the cursor is on in copy mode
2576 copy_cursor_word Word under cursor in copy mode
2577 copy_cursor_x Cursor X position in copy mode
2578 copy_cursor_y Cursor Y position in copy mode
2579 current_file Current configuration file
2580 cursor_character Character at cursor in pane
2581 cursor_flag Pane cursor flag
2582 cursor_x Cursor X position in pane
2583 cursor_y Cursor Y position in pane
2584 history_bytes Number of bytes in window history
2585 history_limit Maximum window history lines
2586 history_size Size of history in lines
2587 hook Name of running hook, if any
2588 hook_pane ID of pane where hook was run, if any
2589 hook_session ID of session where hook was run, if any
2590 hook_session_name Name of session where hook was run, if
2591 any
2592 hook_window ID of window where hook was run, if any
2593 hook_window_name Name of window where hook was run, if any
2594 host #H Hostname of local host
2595 host_short #h Hostname of local host (no domain name)
2596 insert_flag Pane insert flag
2597 keypad_cursor_flag Pane keypad cursor flag
2598 keypad_flag Pane keypad flag
2599 last_window_index Index of last window in session
2600 line Line number in the list
2601 mouse_all_flag Pane mouse all flag
2602 mouse_any_flag Pane mouse any flag
2603 mouse_button_flag Pane mouse button flag
2604 mouse_line Line under mouse, if any
2605 mouse_sgr_flag Pane mouse SGR flag
2606 mouse_standard_flag Pane mouse standard flag
2607 mouse_utf8_flag Pane mouse UTF-8 flag
2608 mouse_word Word under mouse, if any
2609 mouse_x Mouse X position, if any
2610 mouse_y Mouse Y position, if any
2611 origin_flag Pane origin flag
2612 pane_active 1 if active pane
2613 pane_at_bottom 1 if pane is at the bottom of window
2614 pane_at_left 1 if pane is at the left of window
2615 pane_at_right 1 if pane is at the right of window
2616 pane_at_top 1 if pane is at the top of window
2617 pane_bg Pane background colour
2618 pane_bottom Bottom of pane
2619 pane_current_command Current command if available
2620 pane_current_path Current path if available
2621 pane_dead 1 if pane is dead
2622 pane_dead_status Exit status of process in dead pane
2623 pane_fg Pane foreground colour
2624 pane_format 1 if format is for a pane
2625 pane_height Height of pane
2626 pane_id #D Unique pane ID
2627 pane_in_mode 1 if pane is in a mode
2628 pane_index #P Index of pane
2629 pane_input_off 1 if input to pane is disabled
2630 pane_last 1 if last pane
2631 pane_left Left of pane
2632 pane_marked 1 if this is the marked pane
2633 pane_marked_set 1 if a marked pane is set
2634 pane_mode Name of pane mode, if any
2635 pane_path Path of pane (can be set by application)
2636 pane_pid PID of first process in pane
2637 pane_pipe 1 if pane is being piped
2638 pane_right Right of pane
2639 pane_search_string Last search string in copy mode
2640 pane_start_command Command pane started with
2641 pane_synchronized 1 if pane is synchronized
2642 pane_tabs Pane tab positions
2643 pane_title #T Title of pane (can be set by application)
2644 pane_top Top of pane
2645 pane_tty Pseudo terminal of pane
2646 pane_width Width of pane
2647 pid Server PID
2648 rectangle_toggle 1 if rectangle selection is activated
2649 scroll_position Scroll position in copy mode
2650 scroll_region_lower Bottom of scroll region in pane
2651 scroll_region_upper Top of scroll region in pane
2652 search_match Search match if any
2653 search_present 1 if search started in copy mode
2654 selection_active 1 if selection started and changes with
2655 the cursor in copy mode
2656 selection_end_x X position of the end of the selection
2657 selection_end_y Y position of the end of the selection
2658 selection_present 1 if selection started in copy mode
2659 selection_start_x X position of the start of the selection
2660 selection_start_y Y position of the start of the selection
2661 session_activity Time of session last activity
2662 session_alerts List of window indexes with alerts
2663 session_attached Number of clients session is attached to
2664 session_attached_list List of clients session is attached to
2665 session_created Time session created
2666 session_format 1 if format is for a session
2667 session_group Name of session group
2668 session_group_attached Number of clients sessions in group are
2669 attached to
2670 session_group_attached_list List of clients sessions in group are
2671 attached to
2672 session_group_list List of sessions in group
2673 session_group_many_attached 1 if multiple clients attached to
2674 sessions in group
2675 session_group_size Size of session group
2676 session_grouped 1 if session in a group
2677 session_id Unique session ID
2678 session_last_attached Time session last attached
2679 session_many_attached 1 if multiple clients attached
2680 session_marked 1 if this session contains the marked
2681 pane
2682 session_name #S Name of session
2683 session_path Working directory of session
2684 session_stack Window indexes in most recent order
2685 session_windows Number of windows in session
2686 socket_path Server socket path
2687 start_time Server start time
2688 version Server version
2689 window_active 1 if window active
2690 window_active_clients Number of clients viewing this window
2691 window_active_clients_list List of clients viewing this window
2692 window_active_sessions Number of sessions on which this window
2693 is active
2694 window_active_sessions_list List of sessions on which this window is
2695 active
2696 window_activity Time of window last activity
2697 window_activity_flag 1 if window has activity
2698 window_bell_flag 1 if window has bell
2699 window_bigger 1 if window is larger than client
2700 window_cell_height Height of each cell in pixels
2701 window_cell_width Width of each cell in pixels
2702 window_end_flag 1 if window has the highest index
2703 window_flags #F Window flags with # escaped as ##
2704 window_raw_flags Window flags with nothing escaped
2705 window_format 1 if format is for a window
2706 window_height Height of window
2707 window_id Unique window ID
2708 window_index #I Index of window
2709 window_last_flag 1 if window is the last used
2710 window_layout Window layout description, ignoring
2711 zoomed window panes
2712 window_linked 1 if window is linked across sessions
2713 window_linked_sessions Number of sessions this window is linked
2714 to
2715 window_linked_sessions_list List of sessions this window is linked to
2716 window_marked_flag 1 if window contains the marked pane
2717 window_name #W Name of window
2718 window_offset_x X offset into window if larger than
2719 client
2720 window_offset_y Y offset into window if larger than
2721 client
2722 window_panes Number of panes in window
2723 window_silence_flag 1 if window has silence alert
2724 window_stack_index Index in session most recent stack
2725 window_start_flag 1 if window has the lowest index
2726 window_visible_layout Window layout description, respecting
2727 zoomed window panes
2728 window_width Width of window
2729 window_zoomed_flag 1 if window is zoomed
2730 wrap_flag Pane wrap flag
2731
2733 tmux offers various options to specify the colour and attributes of as‐
2734 pects of the interface, for example status-style for the status line. In
2735 addition, embedded styles may be specified in format options, such as
2736 status-left, by enclosing them in ‘#[’ and ‘]’.
2737 A style may be the single term ‘default’ to specify the default style
2739 (which may come from an option, for example status-style in the status
2740 line) or a space or comma separated list of the following:
2741 fg=colour
2743 Set the foreground colour. The colour is one of: black, red,
2744 green, yellow, blue, magenta, cyan, white; if supported the
2745 bright variants brightred, brightgreen, brightyellow; colour0 to
2746 colour255 from the 256-colour set; default for the default
2747 colour; terminal for the terminal default colour; or a hexadeci‐
2748 mal RGB string such as ‘#ffffff’.
2749 bg=colour
2751 Set the background colour.
2752 none Set no attributes (turn off any active attributes).
2754 acs, bright (or bold), dim, underscore, blink, reverse, hidden, italics,
2756 overline, strikethrough, double-underscore, curly-underscore,
2757 dotted-underscore, dashed-underscore
2758 Set an attribute. Any of the attributes may be prefixed with
2759 ‘no’ to unset. acs is the terminal alternate character set.
2760 align=left (or noalign), align=centre, align=right
2762 Align text to the left, centre or right of the available space if
2763 appropriate.
2764 fill=colour
2766 Fill the available space with a background colour if appropriate.
2767 list=on, list=focus, list=left-marker, list=right-marker, nolist
2769 Mark the position of the various window list components in the
2770 status-format option: list=on marks the start of the list;
2771 list=focus is the part of the list that should be kept in focus
2772 if the entire list won't fit in the available space (typically
2773 the current window); list=left-marker and list=right-marker mark
2774 the text to be used to mark that text has been trimmed from the
2775 left or right of the list if there is not enough space.
2776 push-default, pop-default
2778 Store the current colours and attributes as the default or reset
2779 to the previous default. A push-default affects any subsequent
2780 use of the default term until a pop-default. Only one default
2781 may be pushed (each push-default replaces the previous saved de‐
2782 fault).
2783 range=left, range=right, range=window|X, norange
2785 Mark a range in the status-format option. range=left and
2786 range=right are the text used for the ‘StatusLeft’ and
2787 ‘StatusRight’ mouse keys. range=window|X is the range for a win‐
2788 dow passed to the ‘Status’ mouse key, where ‘X’ is a window in‐
2789 dex.
2790 Examples are:
2792 fg=yellow bold underscore blink
2794 bg=black,fg=default,noreverse
2795
2797 tmux distinguishes between names and titles. Windows and sessions have
2798 names, which may be used to specify them in targets and are displayed in
2799 the status line and various lists: the name is the tmux identifier for a
2800 window or session. Only panes have titles. A pane's title is typically
2801 set by the program running inside the pane using an escape sequence (like
2802 it would set the xterm(1) window title in X(7)). Windows themselves do
2803 not have titles - a window's title is the title of its active pane. tmux
2804 itself may set the title of the terminal in which the client is running,
2805 see the set-titles option.
2806 A session's name is set with the new-session and rename-session commands.
2808 A window's name is set with one of:
2809 1. A command argument (such as -n for new-window or new-session).
2811 2. An escape sequence (if the allow-rename option is turned on):
2813 $ printf '\033kWINDOW_NAME\033\\'
2815 3. Automatic renaming, which sets the name to the active command in
2817 the window's active pane. See the automatic-rename option.
2818 When a pane is first created, its title is the hostname. A pane's title
2820 can be set via the title setting escape sequence, for example:
2821 $ printf '\033]2;My Title\033\\'
2823 It can also be modified with the select-pane -T command.
2825
2827 When the server is started, tmux copies the environment into the global
2828 environment; in addition, each session has a session environment. When a
2829 window is created, the session and global environments are merged. If a
2830 variable exists in both, the value from the session environment is used.
2831 The result is the initial environment passed to the new process.
2832 The update-environment session option may be used to update the session
2834 environment from the client when a new session is created or an old reat‐
2835 tached. tmux also initialises the TMUX variable with some internal in‐
2836 formation to allow commands to be executed from inside, and the TERM
2837 variable with the correct terminal setting of ‘screen’.
2838 Variables in both session and global environments may be marked as hid‐
2840 den. Hidden variables are not passed into the environment of new pro‐
2841 cesses and instead can only be used by tmux itself (for example in for‐
2842 mats, see the FORMATS section).
2843 Commands to alter and view the environment are:
2845 set-environment [-Fhgru] [-t target-session] name [value]
2847 (alias: setenv)
2848 Set or unset an environment variable. If -g is used, the change
2849 is made in the global environment; otherwise, it is applied to
2850 the session environment for target-session. If -F is present,
2851 then value is expanded as a format. The -u flag unsets a vari‐
2852 able. -r indicates the variable is to be removed from the envi‐
2853 ronment before starting a new process. -h marks the variable as
2854 hidden.
2855 show-environment [-hgs] [-t target-session] [variable]
2857 (alias: showenv)
2858 Display the environment for target-session or the global environ‐
2859 ment with -g. If variable is omitted, all variables are shown.
2860 Variables removed from the environment are prefixed with ‘-’. If
2861 -s is used, the output is formatted as a set of Bourne shell com‐
2862 mands. -h shows hidden variables (omitted by default).
2863
2865 tmux includes an optional status line which is displayed in the bottom
2866 line of each terminal.
2867 By default, the status line is enabled and one line in height (it may be
2869 disabled or made multiple lines with the status session option) and con‐
2870 tains, from left-to-right: the name of the current session in square
2871 brackets; the window list; the title of the active pane in double quotes;
2872 and the time and date.
2873 Each line of the status line is configured with the status-format option.
2875 The default is made of three parts: configurable left and right sections
2876 (which may contain dynamic content such as the time or output from a
2877 shell command, see the status-left, status-left-length, status-right, and
2878 status-right-length options below), and a central window list. By de‐
2879 fault, the window list shows the index, name and (if any) flag of the
2880 windows present in the current session in ascending numerical order. It
2881 may be customised with the window-status-format and
2882 window-status-current-format options. The flag is one of the following
2883 symbols appended to the window name:
2884 Symbol Meaning
2886 * Denotes the current window.
2887 - Marks the last window (previously selected).
2888 # Window activity is monitored and activity has been
2889 detected.
2890 ! Window bells are monitored and a bell has occurred in the
2891 window.
2892 ~ The window has been silent for the monitor-silence
2893 interval.
2894 M The window contains the marked pane.
2895 Z The window's active pane is zoomed.
2896 The # symbol relates to the monitor-activity window option. The window
2898 name is printed in inverted colours if an alert (bell, activity or si‐
2899 lence) is present.
2900 The colour and attributes of the status line may be configured, the en‐
2902 tire status line using the status-style session option and individual
2903 windows using the window-status-style window option.
2904 The status line is automatically refreshed at interval if it has changed,
2906 the interval may be controlled with the status-interval session option.
2907 Commands related to the status line are as follows:
2909 command-prompt [-1ikNTW] [-I inputs] [-p prompts] [-t target-client]
2911 [template]
2912 Open the command prompt in a client. This may be used from in‐
2913 side tmux to execute commands interactively.
2914 If template is specified, it is used as the command. If present,
2916 -I is a comma-separated list of the initial text for each prompt.
2917 If -p is given, prompts is a comma-separated list of prompts
2918 which are displayed in order; otherwise a single prompt is dis‐
2919 played, constructed from template if it is present, or ‘:’ if
2920 not.
2921 Before the command is executed, the first occurrence of the
2923 string ‘%%’ and all occurrences of ‘%1’ are replaced by the re‐
2924 sponse to the first prompt, all ‘%2’ are replaced with the re‐
2925 sponse to the second prompt, and so on for further prompts. Up
2926 to nine prompt responses may be replaced (‘%1’ to ‘%9’). ‘%%%’
2927 is like ‘%%’ but any quotation marks are escaped.
2928 -1 makes the prompt only accept one key press, in this case the
2930 resulting input is a single character. -k is like -1 but the key
2931 press is translated to a key name. -N makes the prompt only ac‐
2932 cept numeric key presses. -i executes the command every time the
2933 prompt input changes instead of when the user exits the command
2934 prompt. -T tells tmux that the prompt is for a target which af‐
2935 fects what completions are offered when Tab is pressed; -W is
2936 similar but indicates the prompt is for a window.
2937 The following keys have a special meaning in the command prompt,
2939 depending on the value of the status-keys option:
2940 Function vi emacs
2942 Cancel command prompt q Escape
2943 Delete from cursor to start of word C-w
2944 Delete entire command d C-u
2945 Delete from cursor to end D C-k
2946 Execute command Enter Enter
2947 Get next command from history Down
2948 Get previous command from history Up
2949 Insert top paste buffer p C-y
2950 Look for completions Tab Tab
2951 Move cursor left h Left
2952 Move cursor right l Right
2953 Move cursor to end $ C-e
2954 Move cursor to next word w M-f
2955 Move cursor to previous word b M-b
2956 Move cursor to start 0 C-a
2957 Transpose characters C-t
2958 confirm-before [-p prompt] [-t target-client] command
2960 (alias: confirm)
2961 Ask for confirmation before executing command. If -p is given,
2962 prompt is the prompt to display; otherwise a prompt is construc‐
2963 ted from command. It may contain the special character sequences
2964 supported by the status-left option.
2965 This command works only from inside tmux.
2967 display-menu [-O] [-c target-client] [-t target-pane] [-T title] [-x
2969 position] [-y position] name key command ...
2970 (alias: menu)
2971 Display a menu on target-client. target-pane gives the target
2972 for any commands run from the menu.
2973 A menu is passed as a series of arguments: first the menu item
2975 name, second the key shortcut (or empty for none) and third the
2976 command to run when the menu item is chosen. The name and com‐
2977 mand are formats, see the FORMATS and STYLES sections. If the
2978 name begins with a hyphen (-), then the item is disabled (shown
2979 dim) and may not be chosen. The name may be empty for a separa‐
2980 tor line, in which case both the key and command should be omit‐
2981 ted.
2982 -T is a format for the menu title (see FORMATS).
2984 -x and -y give the position of the menu. Both may be a row or
2986 column number, or one of the following special values:
2987 Value Flag Meaning
2989 C Both The centre of the terminal
2990 R -x The right side of the terminal
2991 P Both The bottom left of the pane
2992 M Both The mouse position
2993 W Both The window position on the status line
2994 S -y The line above or below the status line
2995 Or a format, which is expanded including the following additional
2997 variables:
2998 Variable name Replaced with
3000 popup_centre_x Centered in the client
3001 popup_centre_y Centered in the client
3002 popup_height Height of menu or popup
3003 popup_mouse_bottom Bottom of at the mouse
3004 popup_mouse_centre_x Horizontal centre at the
3005 mouse
3006 popup_mouse_centre_y Vertical centre at the mouse
3007 popup_mouse_top Top at the mouse
3008 popup_mouse_x Mouse X position
3009 popup_mouse_y Mouse Y position
3010 popup_pane_bottom Bottom of the pane
3011 popup_pane_left Left of the pane
3012 popup_pane_right Right of the pane
3013 popup_pane_top Top of the pane
3014 popup_status_line_y Above or below the status
3015 line
3016 popup_width Width of menu or popup
3017 popup_window_status_line_x At the window position in
3018 status line
3019 popup_window_status_line_y At the status line showing
3020 the window
3021 Each menu consists of items followed by a key shortcut shown in
3023 brackets. If the menu is too large to fit on the terminal, it is
3024 not displayed. Pressing the key shortcut chooses the correspond‐
3025 ing item. If the mouse is enabled and the menu is opened from a
3026 mouse key binding, releasing the mouse button with an item se‐
3027 lected chooses that item and releasing the mouse button without
3028 an item selected closes the menu. -O changes this behaviour so
3029 that the menu does not close when the mouse button is released
3030 without an item selected the menu is not closed and a mouse but‐
3031 ton must be clicked to choose an item.
3032 The following keys are also available:
3034 Key Function
3036 Enter Choose selected item
3037 Up Select previous item
3038 Down Select next item
3039 q Exit menu
3040 display-message [-aINpv] [-c target-client] [-d delay] [-t target-pane]
3042 [message]
3043 (alias: display)
3044 Display a message. If -p is given, the output is printed to std‐
3045 out, otherwise it is displayed in the target-client status line
3046 for up to delay milliseconds. If delay is not given, the
3047 message-time option is used; a delay of zero waits for a key
3048 press. ‘N’ ignores key presses and closes only after the delay
3049 expires. The format of message is described in the FORMATS sec‐
3050 tion; information is taken from target-pane if -t is given, oth‐
3051 erwise the active pane.
3052 -v prints verbose logging as the format is parsed and -a lists
3054 the format variables and their values.
3055 -I forwards any input read from stdin to the empty pane given by
3057 target-pane.
3058 display-popup [-CE] [-c target-client] [-d start-directory] [-h height]
3060 [-t target-pane] [-w width] [-x position] [-y position]
3061 [shell-command]
3062 (alias: popup)
3063 Display a popup running shell-command on target-client. A popup
3064 is a rectangular box drawn over the top of any panes. Panes are
3065 not updated while a popup is present.
3066 -E closes the popup automatically when shell-command exits. Two
3068 -E closes the popup only if shell-command exited with success.
3069 -x and -y give the position of the popup, they have the same
3071 meaning as for the display-menu command. -w and -h give the
3072 width and height - both may be a percentage (followed by ‘%’).
3073 If omitted, half of the terminal size is used.
3074 The -C flag closes any popup on the client.
3076
3078 tmux maintains a set of named paste buffers. Each buffer may be either
3079 explicitly or automatically named. Explicitly named buffers are named
3080 when created with the set-buffer or load-buffer commands, or by renaming
3081 an automatically named buffer with set-buffer -n. Automatically named
3082 buffers are given a name such as ‘buffer0001’, ‘buffer0002’ and so on.
3083 When the buffer-limit option is reached, the oldest automatically named
3084 buffer is deleted. Explicitly named buffers are not subject to
3085 buffer-limit and may be deleted with the delete-buffer command.
3086 Buffers may be added using copy-mode or the set-buffer and load-buffer
3088 commands, and pasted into a window using the paste-buffer command. If a
3089 buffer command is used and no buffer is specified, the most recently
3090 added automatically named buffer is assumed.
3091 A configurable history buffer is also maintained for each window. By de‐
3093 fault, up to 2000 lines are kept; this can be altered with the
3094 history-limit option (see the set-option command above).
3095 The buffer commands are as follows:
3097 choose-buffer [-NZr] [-F format] [-f filter] [-K key-format] [-O
3099 sort-order] [-t target-pane] [template]
3100 Put a pane into buffer mode, where a buffer may be chosen inter‐
3101 actively from a list. Each buffer is shown on one line. A
3102 shortcut key is shown on the left in brackets allowing for imme‐
3103 diate choice, or the list may be navigated and an item chosen or
3104 otherwise manipulated using the keys below. -Z zooms the pane.
3105 The following keys may be used in buffer mode:
3106 Key Function
3108 Enter Paste selected buffer
3109 Up Select previous buffer
3110 Down Select next buffer
3111 C-s Search by name or content
3112 n Repeat last search
3113 t Toggle if buffer is tagged
3114 T Tag no buffers
3115 C-t Tag all buffers
3116 p Paste selected buffer
3117 P Paste tagged buffers
3118 d Delete selected buffer
3119 D Delete tagged buffers
3120 e Open the buffer in an editor
3121 f Enter a format to filter items
3122 O Change sort field
3123 r Reverse sort order
3124 v Toggle preview
3125 q Exit mode
3126 After a buffer is chosen, ‘%%’ is replaced by the buffer name in
3128 template and the result executed as a command. If template is
3129 not given, "paste-buffer -b '%%'" is used.
3130 -O specifies the initial sort field: one of ‘time’, ‘name’ or
3132 ‘size’. -r reverses the sort order. -f specifies an initial
3133 filter: the filter is a format - if it evaluates to zero, the
3134 item in the list is not shown, otherwise it is shown. If a fil‐
3135 ter would lead to an empty list, it is ignored. -F specifies the
3136 format for each item in the list and -K a format for each short‐
3137 cut key; both are evaluated once for each line. -N starts with‐
3138 out the preview. This command works only if at least one client
3139 is attached.
3140 clear-history [-t target-pane]
3142 (alias: clearhist)
3143 Remove and free the history for the specified pane.
3144 delete-buffer [-b buffer-name]
3146 (alias: deleteb)
3147 Delete the buffer named buffer-name, or the most recently added
3148 automatically named buffer if not specified.
3149 list-buffers [-F format] [-f filter]
3151 (alias: lsb)
3152 List the global buffers. -F specifies the format of each line
3153 and -f a filter. Only buffers for which the filter is true are
3154 shown. See the FORMATS section.
3155 load-buffer [-w] [-b buffer-name] [-t target-client] path
3157 (alias: loadb)
3158 Load the contents of the specified paste buffer from path. If -w
3159 is given, the buffer is also sent to the clipboard for
3160 target-client using the xterm(1) escape sequence, if possible.
3161 paste-buffer [-dpr] [-b buffer-name] [-s separator] [-t target-pane]
3163 (alias: pasteb)
3164 Insert the contents of a paste buffer into the specified pane.
3165 If not specified, paste into the current one. With -d, also
3166 delete the paste buffer. When output, any linefeed (LF) charac‐
3167 ters in the paste buffer are replaced with a separator, by de‐
3168 fault carriage return (CR). A custom separator may be specified
3169 using the -s flag. The -r flag means to do no replacement
3170 (equivalent to a separator of LF). If -p is specified, paste
3171 bracket control codes are inserted around the buffer if the ap‐
3172 plication has requested bracketed paste mode.
3173 save-buffer [-a] [-b buffer-name] path
3175 (alias: saveb)
3176 Save the contents of the specified paste buffer to path. The -a
3177 option appends to rather than overwriting the file.
3178 set-buffer [-aw] [-b buffer-name] [-t target-client] [-n new-buffer-name]
3180 data
3181 (alias: setb)
3182 Set the contents of the specified buffer to data. If -w is
3183 given, the buffer is also sent to the clipboard for target-client
3184 using the xterm(1) escape sequence, if possible. The -a option
3185 appends to rather than overwriting the buffer. The -n option re‐
3186 names the buffer to new-buffer-name.
3187 show-buffer [-b buffer-name]
3189 (alias: showb)
3190 Display the contents of the specified buffer.
3191
3193 Miscellaneous commands are as follows:
3194 clock-mode [-t target-pane]
3196 Display a large clock.
3197 if-shell [-bF] [-t target-pane] shell-command command [command]
3199 (alias: if)
3200 Execute the first command if shell-command returns success or the
3201 second command otherwise. Before being executed, shell-command
3202 is expanded using the rules specified in the FORMATS section, in‐
3203 cluding those relevant to target-pane. With -b, shell-command is
3204 run in the background.
3205 If -F is given, shell-command is not executed but considered suc‐
3207 cess if neither empty nor zero (after formats are expanded).
3208 lock-server
3210 (alias: lock)
3211 Lock each client individually by running the command specified by
3212 the lock-command option.
3213 run-shell [-bC] [-d delay] [-t target-pane] [shell-command]
3215 (alias: run)
3216 Execute shell-command or (with -C) a tmux command in the back‐
3217 ground without creating a window. Before being executed,
3218 shell-command is expanded using the rules specified in the
3219 FORMATS section. With -b, the command is run in the background.
3220 -d waits for delay seconds before starting the command. If -C is
3221 not given, any output to stdout is displayed in view mode (in the
3222 pane specified by -t or the current pane if omitted) after the
3223 command finishes. If the command fails, the exit status is also
3224 displayed.
3225 wait-for [-L | -S | -U] channel
3227 (alias: wait)
3228 When used without options, prevents the client from exiting until
3229 woken using wait-for -S with the same channel. When -L is used,
3230 the channel is locked and any clients that try to lock the same
3231 channel are made to wait until the channel is unlocked with
3232 wait-for -U.
3233
3235 When a tmux client detaches, it prints a message. This may be one of:
3236 detached (from session ...)
3238 The client was detached normally.
3239 detached and SIGHUP
3241 The client was detached and its parent sent the SIGHUP signal
3242 (for example with detach-client -P).
3243 lost tty
3245 The client's tty(4) or pty(4) was unexpectedly destroyed.
3246 terminated
3248 The client was killed with SIGTERM.
3249 too far behind
3251 The client is in control mode and became unable to keep up with
3252 the data from tmux.
3253 exited The server exited when it had no sessions.
3255 server exited
3257 The server exited when it received SIGTERM.
3258 server exited unexpectedly
3260 The server crashed or otherwise exited without telling the client
3261 the reason.
3262
3264 tmux understands some unofficial extensions to terminfo(5). It is not
3265 normally necessary to set these manually, instead the terminal-features
3266 option should be used.
3267 AX An existing extension that tells tmux the terminal supports de‐
3269 fault colours.
3270 Bidi Tell tmux that the terminal supports the VTE bidirectional text
3272 extensions.
3273 Cs, Cr Set the cursor colour. The first takes a single string argument
3275 and is used to set the colour; the second takes no arguments and
3276 restores the default cursor colour. If set, a sequence such as
3277 this may be used to change the cursor colour from inside tmux:
3278 $ printf '\033]12;red\033\\'
3280 Cmg, Clmg, Dsmg, Enmg
3282 Set, clear, disable or enable DECSLRM margins. These are set au‐
3283 tomatically if the terminal reports it is VT420 compatible.
3284 Dsbp, Enbp
3286 Disable and enable bracketed paste. These are set automatically
3287 if the XT capability is present.
3288 Dseks, Eneks
3290 Disable and enable extended keys.
3291 Dsfcs, Enfcs
3293 Disable and enable focus reporting. These are set automatically
3294 if the XT capability is present.
3295 Rect Tell tmux that the terminal supports rectangle operations.
3297 Smol Enable the overline attribute.
3299 Smulx Set a styled underscore. The single parameter is one of: 0 for
3301 no underscore, 1 for normal underscore, 2 for double underscore,
3302 3 for curly underscore, 4 for dotted underscore and 5 for dashed
3303 underscore.
3304 Setulc, ol
3306 Set the underscore colour or reset to the default. The argument
3307 is (red * 65536) + (green * 256) + blue where each is between 0
3308 and 255.
3309 Ss, Se Set or reset the cursor style. If set, a sequence such as this
3311 may be used to change the cursor to an underline:
3312 $ printf '\033[4 q'
3314 If Se is not set, Ss with argument 0 will be used to reset the
3316 cursor style instead.
3317 Sync Start (parameter is 1) or end (parameter is 2) a synchronized up‐
3319 date.
3320 Tc Indicate that the terminal supports the ‘direct colour’ RGB es‐
3322 cape sequence (for example, \e[38;2;255;255;255m).
3323 If supported, this is used for the initialize colour escape se‐
3325 quence (which may be enabled by adding the ‘initc’ and ‘ccc’ ca‐
3326 pabilities to the tmux [22mterminfo(5) entry).
3327 This is equivalent to the RGB terminfo(5) capability.
3329 Ms Store the current buffer in the host terminal's selection (clip‐
3331 board). See the set-clipboard option above and the xterm(1) man
3332 page.
3333 XT This is an existing extension capability that tmux uses to mean
3335 that the terminal supports the xterm(1) title set sequences and
3336 to automatically set some of the capabilities above.
3337
3339 tmux offers a textual interface called control mode. This allows appli‐
3340 cations to communicate with tmux using a simple text-only protocol.
3341 In control mode, a client sends tmux commands or command sequences termi‐
3343 nated by newlines on standard input. Each command will produce one block
3344 of output on standard output. An output block consists of a %begin line
3345 followed by the output (which may be empty). The output block ends with
3346 a %end or %error. %begin and matching %end or %error have three argu‐
3347 ments: an integer time (as seconds from epoch), command number and flags
3348 (currently not used). For example:
3349 %begin 1363006971 2 1
3351 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
3352 %end 1363006971 2 1
3353 The refresh-client -C command may be used to set the size of a client in
3355 control mode.
3356 In control mode, tmux outputs notifications. A notification will never
3358 occur inside an output block.
3359 The following notifications are defined:
3361 %client-detached client
3363 The client has detached.
3364 %client-session-changed client session-id name
3366 The client is now attached to the session with ID session-id,
3367 which is named name.
3368 %continue pane-id
3370 The pane has been continued after being paused (if the
3371 pause-after flag is set, see refresh-client -A).
3372 %exit [reason]
3374 The tmux client is exiting immediately, either because it is not
3375 attached to any session or an error occurred. If present, reason
3376 describes why the client exited.
3377 %extended-output pane-id age ... : value
3379 New form of %output sent when the pause-after flag is set. age
3380 is the time in milliseconds for which tmux had buffered the out‐
3381 put before it was sent. Any subsequent arguments up until a sin‐
3382 gle ‘:’ are for future use and should be ignored.
3383 %layout-change window-id window-layout window-visible-layout window-flags
3385 The layout of a window with ID window-id changed. The new layout
3386 is window-layout. The window's visible layout is
3387 window-visible-layout and the window flags are window-flags.
3388 %output pane-id value
3390 A window pane produced output. value escapes non-printable char‐
3391 acters and backslash as octal \xxx.
3392 %pane-mode-changed pane-id
3394 The pane with ID pane-id has changed mode.
3395 %pause pane-id
3397 The pane has been paused (if the pause-after flag is set).
3398 %session-changed session-id name
3400 The client is now attached to the session with ID session-id,
3401 which is named name.
3402 %session-renamed name
3404 The current session was renamed to name.
3405 %session-window-changed session-id window-id
3407 The session with ID session-id changed its active window to the
3408 window with ID window-id.
3409 %sessions-changed
3411 A session was created or destroyed.
3412 %subscription-changed name session-id window-id window-index pane-id ...
3414 : value
3415 The value of the format associated with subscription name has
3416 changed to value. See refresh-client -B. Any arguments after
3417 pane-id up until a single ‘:’ are for future use and should be
3418 ignored.
3419 %unlinked-window-add window-id
3421 The window with ID window-id was created but is not linked to the
3422 current session.
3423 %window-add window-id
3425 The window with ID window-id was linked to the current session.
3426 %window-close window-id
3428 The window with ID window-id closed.
3429 %window-pane-changed window-id pane-id
3431 The active pane in the window with ID window-id changed to the
3432 pane with ID pane-id.
3433 %window-renamed window-id name
3435 The window with ID window-id was renamed to name.
3436
3438 When tmux is started, it inspects the following environment variables:
3439 EDITOR If the command specified in this variable contains the string
3441 ‘vi’ and VISUAL is unset, use vi-style key bindings. Overrid‐
3442 den by the mode-keys and status-keys options.
3443 HOME The user's login directory. If unset, the passwd(5) database
3445 is consulted.
3446 LC_CTYPE The character encoding locale(1). It is used for two separate
3448 purposes. For output to the terminal, UTF-8 is used if the -u
3449 option is given or if LC_CTYPE contains "UTF-8" or "UTF8".
3450 Otherwise, only ASCII characters are written and non-ASCII
3451 characters are replaced with underscores (‘_’). For input,
3452 tmux always runs with a UTF-8 locale. If en_US.UTF-8 is pro‐
3453 vided by the operating system it is used and LC_CTYPE is ig‐
3454 nored for input. Otherwise, LC_CTYPE tells tmux what the UTF-8
3455 locale is called on the current system. If the locale speci‐
3456 fied by LC_CTYPE is not available or is not a UTF-8 locale,
3457 tmux exits with an error message.
3458 LC_TIME The date and time format locale(1). It is used for locale-de‐
3460 pendent strftime(3) format specifiers.
3461 PWD The current working directory to be set in the global environ‐
3463 ment. This may be useful if it contains symbolic links. If
3464 the value of the variable does not match the current working
3465 directory, the variable is ignored and the result of getcwd(3)
3466 is used instead.
3467 SHELL The absolute path to the default shell for new windows. See
3469 the default-shell option for details.
3470 TMUX_TMPDIR
3472 The parent directory of the directory containing the server
3473 sockets. See the -L option for details.
3474 VISUAL If the command specified in this variable contains the string
3476 ‘vi’, use vi-style key bindings. Overridden by the mode-keys
3477 and status-keys options.
3478
3480 ~/.tmux.conf Default tmux configuration file.
3481 /etc/tmux.conf System-wide configuration file.
3482
3484 To create a new tmux session running vi(1):
3485 $ tmux new-session vi
3487 Most commands have a shorter form, known as an alias. For new-session,
3489 this is new:
3490 $ tmux new vi
3492 Alternatively, the shortest unambiguous form of a command is accepted.
3494 If there are several options, they are listed:
3495 $ tmux n
3497 ambiguous command: n, could be: new-session, new-window, next-window
3498 Within an active session, a new window may be created by typing ‘C-b c’
3500 (Ctrl followed by the ‘b’ key followed by the ‘c’ key).
3501 Windows may be navigated with: ‘C-b 0’ (to select window 0), ‘C-b 1’ (to
3503 select window 1), and so on; ‘C-b n’ to select the next window; and ‘C-b
3504 p’ to select the previous window.
3505 A session may be detached using ‘C-b d’ (or by an external event such as
3507 ssh(1) disconnection) and reattached with:
3508 $ tmux attach-session
3510 Typing ‘C-b ?’ lists the current key bindings in the current window; up
3512 and down may be used to navigate the list or ‘q’ to exit from it.
3513 Commands to be run when the tmux server is started may be placed in the
3515 ~/.tmux.conf configuration file. Common examples include:
3516 Changing the default prefix key:
3518 set-option -g prefix C-a
3520 unbind-key C-b
3521 bind-key C-a send-prefix
3522 Turning the status line off, or changing its colour:
3524 set-option -g status off
3526 set-option -g status-style bg=blue
3527 Setting other options, such as the default command, or locking after 30
3529 minutes of inactivity:
3530 set-option -g default-command "exec /bin/ksh"
3532 set-option -g lock-after-time 1800
3533 Creating new key bindings:
3535 bind-key b set-option status
3537 bind-key / command-prompt "split-window 'exec man %%'"
3538 bind-key S command-prompt "new-window -n %1 'ssh %1'"
3539
3541 pty(4)
3542
3544 Nicholas Marriott <nicholas.marriott@gmail.com>
3545BSD December 5, 2021 BSD