1TMUX(1) BSD General Commands Manual TMUX(1)
2
4 tmux — terminal multiplexer
5
7 tmux [-2CluvV] [-c shell-command] [-f file] [-L socket-name]
8 [-S socket-path] [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
13 detached 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 -C Start in control mode (see the CONTROL MODE section).
44 Given twice (-CC) disables echo.
45 -c shell-command
47 Execute shell-command using the default shell. If neces‐
48 sary, the tmux server will be started to retrieve the
49 default-shell option. This option is for compatibility
50 with sh(1) when tmux is used as a login shell.
51 -f file Specify an alternative configuration file. By default,
53 tmux loads the system configuration file from
54 /etc/tmux.conf, if present, then looks for a user configu‐
55 ration file at ~/.tmux.conf.
56 The configuration file is a set of tmux commands which are
58 executed in sequence when the server is first started.
59 tmux loads configuration files once when the server process
60 has started. The source-file command may be used to load a
61 file later.
62 tmux shows any error messages from commands in configura‐
64 tion files in the first session created, and continues to
65 process the rest of the configuration file.
66 -L socket-name
68 tmux stores the server socket in a directory under
69 TMUX_TMPDIR or /tmp if it is unset. The default socket is
70 named default. This option allows a different socket name
71 to be specified, allowing several independent tmux servers
72 to be run. Unlike -S a full path is not necessary: the
73 sockets are all created in the same directory.
74 If the socket is accidentally removed, the SIGUSR1 signal
76 may be sent to the tmux server process to recreate it (note
77 that this will fail if any parent directories are missing).
78 -l Behave as a login shell. This flag currently has no effect
80 and is for compatibility with other shells when using tmux
81 as a login shell.
82 -S socket-path
84 Specify a full alternative path to the server socket. If
85 -S is specified, the default socket directory is not used
86 and any -L flag is ignored.
87 -u Write UTF-8 output to the terminal even if the first envi‐
89 ronment variable of LC_ALL, LC_CTYPE, or LANG that is set
90 does not contain "UTF-8" or "UTF8".
91 -v Request verbose logging. Log messages will be saved into
93 tmux-client-PID.log and tmux-server-PID.log files in the
94 current directory, where PID is the PID of the server or
95 client process. If -v is specified twice, an additional
96 tmux-out-PID.log file is generated with a copy of every‐
97 thing tmux writes to the terminal.
98 The SIGUSR2 signal may be sent to the tmux server process
100 to toggle logging between on (as if -v was given) and off.
101 -V Report the tmux version.
103 command [flags]
105 This specifies one of a set of commands used to control
106 tmux, as described in the following sections. If no com‐
107 mands are specified, the new-session command is assumed.
108
110 tmux may be controlled from an attached client by using a key combination
111 of a prefix key, ‘C-b’ (Ctrl-b) by default, followed by a command key.
112 The default command key bindings are:
114 C-b Send the prefix key (C-b) through to the application.
116 C-o Rotate the panes in the current window forwards.
117 C-z Suspend the tmux client.
118 ! Break the current pane out of the window.
119 " Split the current pane into two, top and bottom.
120 # List all paste buffers.
121 $ Rename the current session.
122 % Split the current pane into two, left and right.
123 & Kill the current window.
124 ' Prompt for a window index to select.
125 ( Switch the attached client to the previous session.
126 ) Switch the attached client to the next session.
127 , Rename the current window.
128 - Delete the most recently copied buffer of text.
129 . Prompt for an index to move the current window.
130 0 to 9 Select windows 0 to 9.
131 : Enter the tmux command prompt.
132 ; Move to the previously active pane.
133 = Choose which buffer to paste interactively from a list.
134 ? List all key bindings.
135 D Choose a client to detach.
136 L Switch the attached client back to the last session.
137 [ Enter copy mode to copy text or view the history.
138 ] Paste the most recently copied buffer of text.
139 c Create a new window.
140 d Detach the current client.
141 f Prompt to search for text in open windows.
142 i Display some information about the current window.
143 l Move to the previously selected window.
144 n Change to the next window.
145 o Select the next pane in the current window.
146 p Change to the previous window.
147 q Briefly display pane indexes.
148 r Force redraw of the attached client.
149 m Mark the current pane (see select-pane -m).
150 M Clear the marked pane.
151 s Select a new session for the attached client interac‐
152 tively.
153 t Show the time.
154 w Choose the current window interactively.
155 x Kill the current pane.
156 z Toggle zoom state of the current pane.
157 { Swap the current pane with the previous pane.
158 } Swap the current pane with the next pane.
159 ~ Show previous messages from tmux, if any.
160 Page Up Enter copy mode and scroll one page up.
161 Up, Down
162 Left, Right
163 Change to the pane above, below, to the left, or to the
164 right of the current pane.
165 M-1 to M-5 Arrange panes in one of the five preset layouts: even-
166 horizontal, even-vertical, main-horizontal, main-verti‐
167 cal, or tiled.
168 Space Arrange the current window in the next preset layout.
169 M-n Move to the next window with a bell or activity marker.
170 M-o Rotate the panes in the current window backwards.
171 M-p Move to the previous window with a bell or activity
172 marker.
173 C-Up, C-Down
174 C-Left, C-Right
175 Resize the current pane in steps of one cell.
176 M-Up, M-Down
177 M-Left, M-Right
178 Resize the current pane in steps of five cells.
179 Key bindings may be changed with the bind-key and unbind-key commands.
181
183 tmux supports a large number of commands which can be used to control its
184 behaviour. Each command is named and can accept zero or more flags and
185 arguments. They may be bound to a key with the bind-key command or run
186 from the shell prompt, a shell script, a configuration file or the com‐
187 mand prompt. For example, the same set-option command run from the shell
188 prompt, from ~/.tmux.conf and bound to a key may look like:
189 $ tmux set-option -g status-style bg=cyan
191 set-option -g status-style bg=cyan
193 bind-key C set-option -g status-style bg=cyan
195 Here, the command name is ‘set-option’, ‘-g’ is a flag and ‘status-style’
197 and ‘bg=cyan’ are arguments.
198 tmux distinguishes between command parsing and execution. In order to
200 execute a command, tmux needs it to be split up into its name and argu‐
201 ments. This is command parsing. If a command is run from the shell, the
202 shell parses it; from inside tmux or from a configuration file, tmux
203 does. Examples of when tmux parses commands are:
204 - in a configuration file;
206 - typed at the command prompt (see command-prompt);
208 - given to bind-key;
210 - passed as arguments to if-shell or confirm-before.
212 To execute commands, each client has a ‘command queue’. A global command
214 queue not attached to any client is used on startup for configuration
215 files like ~/.tmux.conf. Parsed commands added to the queue are executed
216 in order. Some commands, like if-shell and confirm-before, parse their
217 argument to create a new command which is inserted immediately after
218 themselves. This means that arguments can be parsed twice or more - once
219 when the parent command (such as if-shell) is parsed and again when it
220 parses and executes its command. Commands like if-shell, run-shell and
221 display-panes stop execution of subsequent commands on the queue until
222 something happens - if-shell and run-shell until a shell command finishes
223 and display-panes until a key is pressed. For example, the following
224 commands:
225 new-session; new-window
227 if-shell "true" "split-window"
228 kill-session
229 Will execute new-session, new-window, if-shell, the shell command
231 true(1), split-window and kill-session in that order.
232 The COMMANDS section lists the tmux commands and their arguments.
234
236 This section describes the syntax of commands parsed by tmux, for example
237 in a configuration file or at the command prompt. Note that when com‐
238 mands are entered into the shell, they are parsed by the shell - see for
239 example ksh(1) or csh(1).
240 Each command is terminated by a newline or a semicolon (;). Commands
242 separated by semicolons together form a ‘command sequence’ - if a command
243 in the sequence encounters an error, no subsequent commands are executed.
244 Comments are marked by the unquoted # character - any remaining text
246 after a comment is ignored until the end of the line.
247 If the last character of a line is \, the line is joined with the follow‐
249 ing line (the \ and the newline are completely removed). This is called
250 line continuation and applies both inside and outside quoted strings and
251 in comments, but not inside braces.
252 Command arguments may be specified as strings surrounded by single (')
254 quotes, double quotes (") or braces ({}). This is required when the
255 argument contains any special character. Single and double quoted
256 strings cannot span multiple lines except with line continuation. Braces
257 can span multiple lines.
258 Outside of quotes and inside double quotes, these replacements are per‐
260 formed:
261 - Environment variables preceded by $ are replaced with their
263 value from the global environment (see the GLOBAL AND SESSION
264 ENVIRONMENT section).
265 - A leading ~ or ~user is expanded to the home directory of the
267 current or specified user.
268 - \uXXXX or \uXXXXXXXX is replaced by the Unicode codepoint cor‐
270 responding to the given four or eight digit hexadecimal number.
271 - When preceded (escaped) by a \, the following characters are
273 replaced: \e by the escape character; \r by a carriage return;
274 \n by a newline; and \t by a tab.
275 - \ooo is replaced by a character of the octal value ooo. Three
277 octal digits are required, for example \001. The largest valid
278 character is \377.
279 - Any other characters preceded by \ are replaced by themselves
281 (that is, the \ is removed) and are not treated as having any
282 special meaning - so for example \; will not mark a command
283 sequence and \$ will not expand an environment variable.
284 Braces are similar to single quotes in that the text inside is taken lit‐
286 erally without any replacements but this also includes line continuation.
287 Braces can span multiple lines in which case a literal newline is
288 included in the string. They are designed to avoid the need for addi‐
289 tional escaping when passing a group of tmux or shell commands as an
290 argument (for example to if-shell or pipe-pane). These two examples pro‐
291 duce an identical command - note that no escaping is needed when using
292 {}:
293 if-shell true {
295 display -p 'brace-dollar-foo: }$foo'
296 }
297 if-shell true "\n display -p 'brace-dollar-foo: }\$foo'\n"
299 Braces may be enclosed inside braces, for example:
301 bind x if-shell "true" {
303 if-shell "true" {
304 display "true!"
305 }
306 }
307 Environment variables may be set by using the syntax ‘name=value’, for
309 example ‘HOME=/home/user’. Variables set during parsing are added to the
310 global environment.
311 Commands may be parsed conditionally by surrounding them with ‘%if’,
313 ‘%elif’, ‘%else’ and ‘%endif’. The argument to ‘%if’ and ‘%elif’ is
314 expanded as a format (see FORMATS) and if it evaluates to false (zero or
315 empty), subsequent text is ignored until the closing ‘%elif’, ‘%else’ or
316 ‘%endif’. For example:
317 %if "#{==:#{host},myhost}"
319 set -g status-style bg=red
320 %elif "#{==:#{host},myotherhost}"
321 set -g status-style bg=green
322 %else
323 set -g status-style bg=blue
324 %endif
325 Will change the status line to red if running on ‘myhost’, green if run‐
327 ning on ‘myotherhost’, or blue if running on another host. Conditionals
328 may be given on one line, for example:
329 %if #{==:#{host},myhost} set -g status-style bg=red %endif
331
333 This section describes the commands supported by tmux. Most commands
334 accept the optional -t (and sometimes -s) argument with one of
335 target-client, target-session, target-window, or target-pane. These
336 specify the client, session, window or pane which a command should
337 affect.
338 target-client should be the name of the client, typically the pty(4) file
340 to which the client is connected, for example either of /dev/ttyp1 or
341 ttyp1 for the client attached to /dev/ttyp1. If no client is specified,
342 tmux attempts to work out the client currently in use; if that fails, an
343 error is reported. Clients may be listed with the list-clients command.
344 target-session is tried as, in order:
346 1. A session ID prefixed with a $.
348 2. An exact name of a session (as listed by the list-sessions
350 command).
351 3. The start of a session name, for example ‘mysess’ would match
353 a session named ‘mysession’.
354 4. An fnmatch(3) pattern which is matched against the session
356 name.
357 If the session name is prefixed with an ‘=’, only an exact match is
359 accepted (so ‘=mysess’ will only match exactly ‘mysess’, not
360 ‘mysession’).
361 If a single session is found, it is used as the target session; multiple
363 matches produce an error. If a session is omitted, the current session
364 is used if available; if no current session is available, the most
365 recently used is chosen.
366 target-window (or src-window or dst-window) specifies a window in the
368 form session:window. session follows the same rules as for
369 target-session, and window is looked for in order as:
370 1. A special token, listed below.
372 2. A window index, for example ‘mysession:1’ is window 1 in ses‐
374 sion ‘mysession’.
375 3. A window ID, such as @1.
377 4. An exact window name, such as ‘mysession:mywindow’.
379 5. The start of a window name, such as ‘mysession:mywin’.
381 6. As an fnmatch(3) pattern matched against the window name.
383 Like sessions, a ‘=’ prefix will do an exact match only. An empty window
385 name specifies the next unused index if appropriate (for example the
386 new-window and link-window commands) otherwise the current window in
387 session is chosen.
388 The following special tokens are available to indicate particular win‐
390 dows. Each has a single-character alternative form.
391 Token Meaning
393 {start} ^ The lowest-numbered window
394 {end} $ The highest-numbered window
395 {last} ! The last (previously current) window
396 {next} + The next window by number
397 {previous} - The previous window by number
398 target-pane (or src-pane or dst-pane) may be a pane ID or takes a similar
400 form to target-window but with the optional addition of a period followed
401 by a pane index or pane ID, for example: ‘mysession:mywindow.1’. If the
402 pane index is omitted, the currently active pane in the specified window
403 is used. The following special tokens are available for the pane index:
404 Token Meaning
406 {last} ! The last (previously active) pane
407 {next} + The next pane by number
408 {previous} - The previous pane by number
409 {top} The top pane
410 {bottom} The bottom pane
411 {left} The leftmost pane
412 {right} The rightmost pane
413 {top-left} The top-left pane
414 {top-right} The top-right pane
415 {bottom-left} The bottom-left pane
416 {bottom-right} The bottom-right pane
417 {up-of} The pane above the active pane
418 {down-of} The pane below the active pane
419 {left-of} The pane to the left of the active pane
420 {right-of} The pane to the right of the active pane
421 The tokens ‘+’ and ‘-’ may be followed by an offset, for example:
423 select-window -t:+2
425 In addition, target-session, target-window or target-pane may consist
427 entirely of the token ‘{mouse}’ (alternative form ‘=’) to specify the
428 session, window or pane where the most recent mouse event occurred (see
429 the MOUSE SUPPORT section) or ‘{marked}’ (alternative form ‘~’) to spec‐
430 ify the marked pane (see select-pane -m).
431 Sessions, window and panes are each numbered with a unique ID; session
433 IDs are prefixed with a ‘$’, windows with a ‘@’, and panes with a ‘%’.
434 These are unique and are unchanged for the life of the session, window or
435 pane in the tmux server. The pane ID is passed to the child process of
436 the pane in the TMUX_PANE environment variable. IDs may be displayed
437 using the ‘session_id’, ‘window_id’, or ‘pane_id’ formats (see the
438 FORMATS section) and the display-message, list-sessions, list-windows or
439 list-panes commands.
440 shell-command arguments are sh(1) commands. This may be a single argu‐
442 ment passed to the shell, for example:
443 new-window 'vi /etc/passwd'
445 Will run:
447 /bin/sh -c 'vi /etc/passwd'
449 Additionally, the new-window, new-session, split-window, respawn-window
451 and respawn-pane commands allow shell-command to be given as multiple
452 arguments and executed directly (without ‘sh -c’). This can avoid issues
453 with shell quoting. For example:
454 $ tmux new-window vi /etc/passwd
456 Will run vi(1) directly without invoking the shell.
458 command [arguments] refers to a tmux command, either passed with the com‐
460 mand and arguments separately, for example:
461 bind-key F1 set-option status off
463 Or passed as a single string argument in .tmux.conf, for example:
465 bind-key F1 { set-option status off }
467 Example tmux commands include:
469 refresh-client -t/dev/ttyp2
471 rename-session -tfirst newname
473 set-option -wt:0 monitor-activity on
475 new-window ; split-window -d
477 bind-key R source-file ~/.tmux.conf \; \
479 display-message "source-file done"
480 Or from sh(1):
482 $ tmux kill-window -t :1
484 $ tmux new-window \; split-window -d
486 $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach
488
490 The tmux server manages clients, sessions, windows and panes. Clients
491 are attached to sessions to interact with them, either when they are cre‐
492 ated with the new-session command, or later with the attach-session com‐
493 mand. Each session has one or more windows linked into it. Windows may
494 be linked to multiple sessions and are made up of one or more panes, each
495 of which contains a pseudo terminal. Commands for creating, linking and
496 otherwise manipulating windows are covered in the WINDOWS AND PANES sec‐
497 tion.
498 The following commands are available to manage clients and sessions:
500 attach-session [-dErx] [-c working-directory] [-t target-session]
502 (alias: attach)
503 If run from outside tmux, create a new client in the current ter‐
504 minal and attach it to target-session. If used from inside,
505 switch the current client. If -d is specified, any other clients
506 attached to the session are detached. If -x is given, send
507 SIGHUP to the parent process of the client as well as detaching
508 the client, typically causing it to exit. -r signifies the
509 client is read-only (only keys bound to the detach-client or
510 switch-client commands have any effect)
511 If no server is started, attach-session will attempt to start it;
513 this will fail unless sessions are created in the configuration
514 file.
515 The target-session rules for attach-session are slightly
517 adjusted: if tmux needs to select the most recently used session,
518 it will prefer the most recently used unattached session.
519 -c will set the session working directory (used for new windows)
521 to working-directory.
522 If -E is used, the update-environment option will not be applied.
524 detach-client [-aP] [-E shell-command] [-s target-session] [-t
526 target-client]
527 (alias: detach)
528 Detach the current client if bound to a key, the client specified
529 with -t, or all clients currently attached to the session speci‐
530 fied by -s. The -a option kills all but the client given with
531 -t. If -P is given, send SIGHUP to the parent process of the
532 client, typically causing it to exit. With -E, run shell-command
533 to replace the client.
534 has-session [-t target-session]
536 (alias: has)
537 Report an error and exit with 1 if the specified session does not
538 exist. If it does exist, exit with 0.
539 kill-server
541 Kill the tmux server and clients and destroy all sessions.
542 kill-session [-aC] [-t target-session]
544 Destroy the given session, closing any windows linked to it and
545 no other sessions, and detaching all clients attached to it. If
546 -a is given, all sessions but the specified one is killed. The
547 -C flag clears alerts (bell, activity, or silence) in all windows
548 linked to the session.
549 list-clients [-F format] [-t target-session]
551 (alias: lsc)
552 List all clients attached to the server. For the meaning of the
553 -F flag, see the FORMATS section. If target-session is speci‐
554 fied, list only clients connected to that session.
555 list-commands [-F format]
557 (alias: lscm)
558 List the syntax of all commands supported by tmux.
559 list-sessions [-F format]
561 (alias: ls)
562 List all sessions managed by the server. For the meaning of the
563 -F flag, see the FORMATS section.
564 lock-client [-t target-client]
566 (alias: lockc)
567 Lock target-client, see the lock-server command.
568 lock-session [-t target-session]
570 (alias: locks)
571 Lock all clients attached to target-session.
572 new-session [-AdDEPX] [-c start-directory] [-F format] [-n window-name]
574 [-s session-name] [-t group-name] [-x width] [-y height]
575 [shell-command]
576 (alias: new)
577 Create a new session with name session-name.
578 The new session is attached to the current terminal unless -d is
580 given. window-name and shell-command are the name of and shell
581 command to execute in the initial window. With -d, the initial
582 size comes from the global default-size option; -x and -y can be
583 used to specify a different size. ‘-’ uses the size of the cur‐
584 rent client if any. If -x or -y is given, the default-size
585 option is set for the session.
586 If run from a terminal, any termios(4) special characters are
588 saved and used for new windows in the new session.
589 The -A flag makes new-session behave like attach-session if
591 session-name already exists; in this case, -D behaves like -d to
592 attach-session, and -X behaves like -x to attach-session.
593 If -t is given, it specifies a session group. Sessions in the
595 same group share the same set of windows - new windows are linked
596 to all sessions in the group and any windows closed removed from
597 all sessions. The current and previous window and any session
598 options remain independent and any session in a group may be
599 killed without affecting the others. The group-name argument may
600 be:
601 1. the name of an existing group, in which case the new ses‐
603 sion is added to that group;
604 2. the name of an existing session - the new session is
606 added to the same group as that session, creating a new
607 group if necessary;
608 3. the name for a new group containing only the new session.
610 -n and shell-command are invalid if -t is used.
612 The -P option prints information about the new session after it
614 has been created. By default, it uses the format
615 ‘#{session_name}:’ but a different format may be specified with
616 -F.
617 If -E is used, the update-environment option will not be applied.
619 refresh-client [-cDlLRSU] [-C XxY] [-F flags] [-t target-client]
621 [adjustment]
622 (alias: refresh)
623 Refresh the current client if bound to a key, or a single client
624 if one is given with -t. If -S is specified, only update the
625 client's status line.
626 The -U, -D, -L -R, and -c flags allow the visible portion of a
628 window which is larger than the client to be changed. -U moves
629 the visible part up by adjustment rows and -D down, -L left by
630 adjustment columns and -R right. -c returns to tracking the cur‐
631 sor automatically. If adjustment is omitted, 1 is used. Note
632 that the visible position is a property of the client not of the
633 window, changing the current window in the attached session will
634 reset it.
635 -C sets the width and height of a control client and -F sets a
637 comma-separated list of flags. Currently the only flag available
638 is ‘no-output’ to disable receiving pane output.
639 -l requests the clipboard from the client using the xterm(1)
641 escape sequence and stores it in a new paste buffer.
642 -L, -R, -U and -D move the visible portion of the window left,
644 right, up or down by adjustment, if the window is larger than the
645 client. -c resets so that the position follows the cursor. See
646 the window-size option.
647 rename-session [-t target-session] new-name
649 (alias: rename)
650 Rename the session to new-name.
651 show-messages [-JT] [-t target-client]
653 (alias: showmsgs)
654 Show client messages or server information. Any messages dis‐
655 played on the status line are saved in a per-client message log,
656 up to a maximum of the limit set by the message-limit server
657 option. With -t, display the log for target-client. -J and -T
658 show debugging information about jobs and terminals.
659 source-file [-nqv] path ...
661 (alias: source)
662 Execute commands from one or more files specified by path (which
663 may be glob(7) patterns). If -q is given, no error will be
664 returned if path does not exist. With -n, the file is parsed but
665 no commands are executed. -v shows the parsed commands and line
666 numbers if possible.
667 start-server
669 (alias: start)
670 Start the tmux server, if not already running, without creating
671 any sessions.
672 suspend-client [-t target-client]
674 (alias: suspendc)
675 Suspend a client by sending SIGTSTP (tty stop).
676 switch-client [-Elnpr] [-c target-client] [-t target-session] [-T
678 key-table]
679 (alias: switchc)
680 Switch the current session for client target-client to
681 target-session. As a special case, -t may refer to a pane (a
682 target that contains ‘:’, ‘.’ or ‘%’), in which case the session,
683 window and pane are all changed. If -l, -n or -p is used, the
684 client is moved to the last, next or previous session respec‐
685 tively. -r toggles whether a client is read-only (see the
686 attach-session command).
687 If -E is used, update-environment option will not be applied.
689 -T sets the client's key table; the next key from the client will
691 be interpreted from key-table. This may be used to configure
692 multiple prefix keys, or to bind commands to sequences of keys.
693 For example, to make typing ‘abc’ run the list-keys command:
694 bind-key -Ttable2 c list-keys
696 bind-key -Ttable1 b switch-client -Ttable2
697 bind-key -Troot a switch-client -Ttable1
698
700 A tmux window may be in one of two modes. The default permits direct
701 access to the terminal attached to the window. The other is copy mode,
702 which permits a section of a window or its history to be copied to a
703 paste buffer for later insertion into another window. This mode is
704 entered with the copy-mode command, bound to ‘[’ by default. It is also
705 entered when a command that produces output, such as list-keys, is exe‐
706 cuted from a key binding.
707 In copy mode an indicator is displayed in the top-right corner of the
709 pane with the current position and the number of lines in the history.
710 Commands are sent to copy mode using the -X flag to the send-keys com‐
712 mand. When a key is pressed, copy mode automatically uses one of two key
713 tables, depending on the mode-keys option: copy-mode for emacs, or
714 copy-mode-vi for vi. Key tables may be viewed with the list-keys com‐
715 mand.
716 The following commands are supported in copy mode:
718 Command vi emacs
720 append-selection
721 append-selection-and-cancel A
722 back-to-indentation ^ M-m
723 begin-selection Space C-Space
724 bottom-line L
725 cancel q Escape
726 clear-selection Escape C-g
727 copy-end-of-line [<prefix>] D C-k
728 copy-line [<prefix>]
729 copy-pipe <command> [<prefix>]
730 copy-pipe-no-clear <command> [<prefix>]
731 copy-pipe-and-cancel <command> [<prefix>]
732 copy-selection [<prefix>]
733 copy-selection-no-clear [<prefix>]
734 copy-selection-and-cancel [<prefix>] Enter M-w
735 cursor-down j Down
736 cursor-left h Left
737 cursor-right l Right
738 cursor-up k Up
739 end-of-line $ C-e
740 goto-line <line> : g
741 halfpage-down C-d M-Down
742 halfpage-down-and-cancel
743 halfpage-up C-u M-Up
744 history-bottom G M->
745 history-top g M-<
746 jump-again ; ;
747 jump-backward <to> F F
748 jump-forward <to> f f
749 jump-reverse , ,
750 jump-to-backward <to> T
751 jump-to-forward <to> t
752 middle-line M M-r
753 next-matching-bracket % M-C-f
754 next-paragraph } M-}
755 next-space W
756 next-space-end E
757 next-word w
758 next-word-end e M-f
759 other-end o
760 page-down C-f PageDown
761 page-down-and-cancel
762 page-up C-b PageUp
763 previous-matching-bracket M-C-b
764 previous-paragraph { M-{
765 previous-space B
766 previous-word b M-b
767 rectangle-toggle v R
768 scroll-down C-e C-Down
769 scroll-down-and-cancel
770 scroll-up C-y C-Up
771 search-again n n
772 search-backward <for> ?
773 search-forward <for> /
774 search-backward-incremental <for> C-r
775 search-forward-incremental <for> C-s
776 search-reverse N N
777 select-line V
778 select-word
779 start-of-line 0 C-a
780 stop-selection
781 top-line H M-R
782 Copy commands may take an optional buffer prefix argument which is used
784 to generate the buffer name (the default is ‘buffer’ so buffers are named
785 ‘buffer0’, ‘buffer1’ and so on). Pipe commands take a command argument
786 which is the command to which the copied text is piped. The
787 ‘-and-cancel’ variants of some commands exit copy mode after they have
788 completed (for copy commands) or when the cursor reaches the bottom (for
789 scrolling commands). ‘-no-clear’ variants do not clear the selection.
790 The next and previous word keys use space and the ‘-’, ‘_’ and ‘@’ char‐
792 acters as word delimiters by default, but this can be adjusted by setting
793 the word-separators session option. Next word moves to the start of the
794 next word, next word end to the end of the next word and previous word to
795 the start of the previous word. The three next and previous space keys
796 work similarly but use a space alone as the word separator.
797 The jump commands enable quick movement within a line. For instance,
799 typing ‘f’ followed by ‘/’ will move the cursor to the next ‘/’ character
800 on the current line. A ‘;’ will then jump to the next occurrence.
801 Commands in copy mode may be prefaced by an optional repeat count. With
803 vi key bindings, a prefix is entered using the number keys; with emacs,
804 the Alt (meta) key and a number begins prefix entry.
805 The synopsis for the copy-mode command is:
807 copy-mode [-Meu] [-t target-pane]
809 Enter copy mode. The -u option scrolls one page up. -M begins a
810 mouse drag (only valid if bound to a mouse key binding, see MOUSE
811 SUPPORT). -e specifies that scrolling to the bottom of the his‐
812 tory (to the visible screen) should exit copy mode. While in
813 copy mode, pressing a key other than those used for scrolling
814 will disable this behaviour. This is intended to allow fast
815 scrolling through a pane's history, for example with:
816 bind PageUp copy-mode -eu
818 Each window displayed by tmux may be split into one or more panes; each
820 pane takes up a certain area of the display and is a separate terminal.
821 A window may be split into panes using the split-window command. Windows
822 may be split horizontally (with the -h flag) or vertically. Panes may be
823 resized with the resize-pane command (bound to ‘C-Up’, ‘C-Down’ ‘C-Left’
824 and ‘C-Right’ by default), the current pane may be changed with the
825 select-pane command and the rotate-window and swap-pane commands may be
826 used to swap panes without changing their position. Panes are numbered
827 beginning from zero in the order they are created.
828 A number of preset layouts are available. These may be selected with the
830 select-layout command or cycled with next-layout (bound to ‘Space’ by
831 default); once a layout is chosen, panes within it may be moved and
832 resized as normal.
833 The following layouts are supported:
835 even-horizontal
837 Panes are spread out evenly from left to right across the window.
838 even-vertical
840 Panes are spread evenly from top to bottom.
841 main-horizontal
843 A large (main) pane is shown at the top of the window and the
844 remaining panes are spread from left to right in the leftover
845 space at the bottom. Use the main-pane-height window option to
846 specify the height of the top pane.
847 main-vertical
849 Similar to main-horizontal but the large pane is placed on the
850 left and the others spread from top to bottom along the right.
851 See the main-pane-width window option.
852 tiled Panes are spread out as evenly as possible over the window in
854 both rows and columns.
855 In addition, select-layout may be used to apply a previously used layout
857 - the list-windows command displays the layout of each window in a form
858 suitable for use with select-layout. For example:
859 $ tmux list-windows
861 0: ksh [159x48]
862 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
863 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
864 tmux automatically adjusts the size of the layout for the current window
866 size. Note that a layout cannot be applied to a window with more panes
867 than that from which the layout was originally defined.
868 Commands related to windows and panes are as follows:
870 break-pane [-dP] [-F format] [-n window-name] [-s src-pane] [-t
872 dst-window]
873 (alias: breakp)
874 Break src-pane off from its containing window to make it the only
875 pane in dst-window. If -d is given, the new window does not
876 become the current window. The -P option prints information
877 about the new window after it has been created. By default, it
878 uses the format ‘#{session_name}:#{window_index}’ but a different
879 format may be specified with -F.
880 capture-pane [-aepPqCJ] [-b buffer-name] [-E end-line] [-S start-line]
882 [-t target-pane]
883 (alias: capturep)
884 Capture the contents of a pane. If -p is given, the output goes
885 to stdout, otherwise to the buffer specified with -b or a new
886 buffer if omitted. If -a is given, the alternate screen is used,
887 and the history is not accessible. If no alternate screen
888 exists, an error will be returned unless -q is given. If -e is
889 given, the output includes escape sequences for text and back‐
890 ground attributes. -C also escapes non-printable characters as
891 octal \xxx. -J joins wrapped lines and preserves trailing spaces
892 at each line's end. -P captures only any output that the pane
893 has received that is the beginning of an as-yet incomplete escape
894 sequence.
895 -S and -E specify the starting and ending line numbers, zero is
897 the first line of the visible pane and negative numbers are lines
898 in the history. ‘-’ to -S is the start of the history and to -E
899 the end of the visible pane. The default is to capture only the
900 visible contents of the pane.
901 choose-client [-NZ] [-F format] [-f filter] [-O sort-order] [-t
903 target-pane] [template]
904 Put a pane into client mode, allowing a client to be selected
905 interactively from a list. -Z zooms the pane. The following
906 keys may be used in client mode:
907 Key Function
909 Enter Choose selected client
910 Up Select previous client
911 Down Select next client
912 C-s Search by name
913 n Repeat last search
914 t Toggle if client is tagged
915 T Tag no clients
916 C-t Tag all clients
917 d Detach selected client
918 D Detach tagged clients
919 x Detach and HUP selected client
920 X Detach and HUP tagged clients
921 z Suspend selected client
922 Z Suspend tagged clients
923 f Enter a format to filter items
924 O Change sort order
925 v Toggle preview
926 q Exit mode
927 After a client is chosen, ‘%%’ is replaced by the client name in
929 template and the result executed as a command. If template is
930 not given, "detach-client -t '%%'" is used.
931 -O specifies the initial sort order: one of ‘name’, ‘size’,
933 ‘creation’, or ‘activity’. -f specifies an initial filter: the
934 filter is a format - if it evaluates to zero, the item in the
935 list is not shown, otherwise it is shown. If a filter would lead
936 to an empty list, it is ignored. -F specifies the format for
937 each item in the list. -N starts without the preview. This com‐
938 mand works only if at least one client is attached.
939 choose-tree [-GNswZ] [-F format] [-f filter] [-O sort-order] [-t
941 target-pane] [template]
942 Put a pane into tree mode, where a session, window or pane may be
943 chosen interactively from a list. -s starts with sessions col‐
944 lapsed and -w with windows collapsed. -Z zooms the pane. The
945 following keys may be used in tree mode:
946 Key Function
948 Enter Choose selected item
949 Up Select previous item
950 Down Select next item
951 x Kill selected item
952 X Kill tagged items
953 < Scroll list of previews left
954 > Scroll list of previews right
955 C-s Search by name
956 n Repeat last search
957 t Toggle if item is tagged
958 T Tag no items
959 C-t Tag all items
960 : Run a command for each tagged item
961 f Enter a format to filter items
962 O Change sort order
963 v Toggle preview
964 q Exit mode
965 After a session, window or pane is chosen, ‘%%’ is replaced by
967 the target in template and the result executed as a command. If
968 template is not given, "switch-client -t '%%'" is used.
969 -O specifies the initial sort order: one of ‘index’, ‘name’, or
971 ‘time’. -f specifies an initial filter: the filter is a format -
972 if it evaluates to zero, the item in the list is not shown, oth‐
973 erwise it is shown. If a filter would lead to an empty list, it
974 is ignored. -F specifies the format for each item in the tree.
975 -N starts without the preview. -G includes all sessions in any
976 session groups in the tree rather than only the first. This com‐
977 mand works only if at least one client is attached.
978 display-panes [-b] [-d duration] [-t target-client] [template]
980 (alias: displayp)
981 Display a visible indicator of each pane shown by target-client.
982 See the display-panes-colour and display-panes-active-colour ses‐
983 sion options. The indicator is closed when a key is pressed or
984 duration milliseconds have passed. If -d is not given,
985 display-panes-time is used. A duration of zero means the indica‐
986 tor stays until a key is pressed. While the indicator is on
987 screen, a pane may be chosen with the ‘0’ to ‘9’ keys, which will
988 cause template to be executed as a command with ‘%%’ substituted
989 by the pane ID. The default template is "select-pane -t '%%'".
990 With -b, other commands are not blocked from running until the
991 indicator is closed.
992 find-window [-rCNTZ] [-t target-pane] match-string
994 (alias: findw)
995 Search for a fnmatch(3) pattern or, with -r, regular expression
996 match-string in window names, titles, and visible content (but
997 not history). The flags control matching behavior: -C matches
998 only visible window contents, -N matches only the window name and
999 -T matches only the window title. The default is -CNT. -Z zooms
1000 the pane.
1001 This command works only if at least one client is attached.
1003 join-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane]
1005 (alias: joinp)
1006 Like split-window, but instead of splitting dst-pane and creating
1007 a new pane, split it and move src-pane into the space. This can
1008 be used to reverse break-pane. The -b option causes src-pane to
1009 be joined to left of or above dst-pane.
1010 If -s is omitted and a marked pane is present (see select-pane
1012 -m), the marked pane is used rather than the current pane.
1013 kill-pane [-a] [-t target-pane]
1015 (alias: killp)
1016 Destroy the given pane. If no panes remain in the containing
1017 window, it is also destroyed. The -a option kills all but the
1018 pane given with -t.
1019 kill-window [-a] [-t target-window]
1021 (alias: killw)
1022 Kill the current window or the window at target-window, removing
1023 it from any sessions to which it is linked. The -a option kills
1024 all but the window given with -t.
1025 last-pane [-de] [-t target-window]
1027 (alias: lastp)
1028 Select the last (previously selected) pane. -e enables or -d
1029 disables input to the pane.
1030 last-window [-t target-session]
1032 (alias: last)
1033 Select the last (previously selected) window. If no
1034 target-session is specified, select the last window of the cur‐
1035 rent session.
1036 link-window [-adk] [-s src-window] [-t dst-window]
1038 (alias: linkw)
1039 Link the window at src-window to the specified dst-window. If
1040 dst-window is specified and no such window exists, the src-window
1041 is linked there. With -a, the window is moved to the next index
1042 up (following windows are moved if necessary). If -k is given
1043 and dst-window exists, it is killed, otherwise an error is gener‐
1044 ated. If -d is given, the newly linked window is not selected.
1045 list-panes [-as] [-F format] [-t target]
1047 (alias: lsp)
1048 If -a is given, target is ignored and all panes on the server are
1049 listed. If -s is given, target is a session (or the current ses‐
1050 sion). If neither is given, target is a window (or the current
1051 window). For the meaning of the -F flag, see the FORMATS sec‐
1052 tion.
1053 list-windows [-a] [-F format] [-t target-session]
1055 (alias: lsw)
1056 If -a is given, list all windows on the server. Otherwise, list
1057 windows in the current session or in target-session. For the
1058 meaning of the -F flag, see the FORMATS section.
1059 move-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane]
1061 (alias: movep)
1062 Like join-pane, but src-pane and dst-pane may belong to the same
1063 window.
1064 move-window [-ardk] [-s src-window] [-t dst-window]
1066 (alias: movew)
1067 This is similar to link-window, except the window at src-window
1068 is moved to dst-window. With -r, all windows in the session are
1069 renumbered in sequential order, respecting the base-index option.
1070 new-window [-adkP] [-c start-directory] [-e environment] [-F format] [-n
1072 window-name] [-t target-window] [shell-command]
1073 (alias: neww)
1074 Create a new window. With -a, the new window is inserted at the
1075 next index up from the specified target-window, moving windows up
1076 if necessary, otherwise target-window is the new window location.
1077 If -d is given, the session does not make the new window the cur‐
1079 rent window. target-window represents the window to be created;
1080 if the target already exists an error is shown, unless the -k
1081 flag is used, in which case it is destroyed. shell-command is
1082 the command to execute. If shell-command is not specified, the
1083 value of the default-command option is used. -c specifies the
1084 working directory in which the new window is created.
1085 When the shell command completes, the window closes. See the
1087 remain-on-exit option to change this behaviour.
1088 -e takes the form ‘VARIABLE=value’ and sets an environment vari‐
1090 able for the newly created window; it may be specified multiple
1091 times.
1092 The TERM environment variable must be set to ‘screen’ or ‘tmux’
1094 for all programs running inside tmux. New windows will automati‐
1095 cally have ‘TERM=screen’ added to their environment, but care
1096 must be taken not to reset this in shell start-up files or by the
1097 -e option.
1098 The -P option prints information about the new window after it
1100 has been created. By default, it uses the format
1101 ‘#{session_name}:#{window_index}’ but a different format may be
1102 specified with -F.
1103 next-layout [-t target-window]
1105 (alias: nextl)
1106 Move a window to the next layout and rearrange the panes to fit.
1107 next-window [-a] [-t target-session]
1109 (alias: next)
1110 Move to the next window in the session. If -a is used, move to
1111 the next window with an alert.
1112 pipe-pane [-IOo] [-t target-pane] [shell-command]
1114 (alias: pipep)
1115 Pipe output sent by the program in target-pane to a shell command
1116 or vice versa. A pane may only be connected to one command at a
1117 time, any existing pipe is closed before shell-command is exe‐
1118 cuted. The shell-command string may contain the special charac‐
1119 ter sequences supported by the status-left option. If no
1120 shell-command is given, the current pipe (if any) is closed.
1121 -I and -O specify which of the shell-command output streams are
1123 connected to the pane: with -I stdout is connected (so anything
1124 shell-command prints is written to the pane as if it were typed);
1125 with -O stdin is connected (so any output in the pane is piped to
1126 shell-command). Both may be used together and if neither are
1127 specified, -O is used.
1128 The -o option only opens a new pipe if no previous pipe exists,
1130 allowing a pipe to be toggled with a single key, for example:
1131 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
1133 previous-layout [-t target-window]
1135 (alias: prevl)
1136 Move to the previous layout in the session.
1137 previous-window [-a] [-t target-session]
1139 (alias: prev)
1140 Move to the previous window in the session. With -a, move to the
1141 previous window with an alert.
1142 rename-window [-t target-window] new-name
1144 (alias: renamew)
1145 Rename the current window, or the window at target-window if
1146 specified, to new-name.
1147 resize-pane [-DLMRUZ] [-t target-pane] [-x width] [-y height]
1149 [adjustment]
1150 (alias: resizep)
1151 Resize a pane, up, down, left or right by adjustment with -U, -D,
1152 -L or -R, or to an absolute size with -x or -y. The adjustment
1153 is given in lines or cells (the default is 1).
1154 With -Z, the active pane is toggled between zoomed (occupying the
1156 whole of the window) and unzoomed (its normal position in the
1157 layout).
1158 -M begins mouse resizing (only valid if bound to a mouse key
1160 binding, see MOUSE SUPPORT).
1161 resize-window [-aADLRU] [-t target-window] [-x width] [-y height]
1163 [adjustment]
1164 (alias: resizew)
1165 Resize a window, up, down, left or right by adjustment with -U,
1166 -D, -L or -R, or to an absolute size with -x or -y. The
1167 adjustment is given in lines or cells (the default is 1). -A
1168 sets the size of the largest session containing the window; -a
1169 the size of the smallest. This command will automatically set
1170 window-size to manual in the window options.
1171 respawn-pane [-k] [-c start-directory] [-e environment] [-t target-pane]
1173 [shell-command]
1174 (alias: respawnp)
1175 Reactivate a pane in which the command has exited (see the
1176 remain-on-exit window option). If shell-command is not given,
1177 the command used when the pane was created is executed. The pane
1178 must be already inactive, unless -k is given, in which case any
1179 existing command is killed. -c specifies a new working directory
1180 for the pane. The -e option has the same meaning as for the
1181 new-window command.
1182 respawn-window [-k] [-c start-directory] [-e environment] [-t
1184 target-window] [shell-command]
1185 (alias: respawnw)
1186 Reactivate a window in which the command has exited (see the
1187 remain-on-exit window option). If shell-command is not given,
1188 the command used when the window was created is executed. The
1189 window must be already inactive, unless -k is given, in which
1190 case any existing command is killed. -c specifies a new working
1191 directory for the window. The -e option has the same meaning as
1192 for the new-window command.
1193 rotate-window [-DU] [-t target-window]
1195 (alias: rotatew)
1196 Rotate the positions of the panes within a window, either upward
1197 (numerically lower) with -U or downward (numerically higher).
1198 select-layout [-Enop] [-t target-pane] [layout-name]
1200 (alias: selectl)
1201 Choose a specific layout for a window. If layout-name is not
1202 given, the last preset layout used (if any) is reapplied. -n and
1203 -p are equivalent to the next-layout and previous-layout com‐
1204 mands. -o applies the last set layout if possible (undoes the
1205 most recent layout change). -E spreads the current pane and any
1206 panes next to it out evenly.
1207 select-pane [-DdeLlMmRU] [-T title] [-t target-pane]
1209 (alias: selectp)
1210 Make pane target-pane the active pane in window target-window.
1211 If one of -D, -L, -R, or -U is used, respectively the pane below,
1212 to the left, to the right, or above the target pane is used. -l
1213 is the same as using the last-pane command. -e enables or -d
1214 disables input to the pane. -T sets the pane title.
1215 -m and -M are used to set and clear the marked pane. There is
1217 one marked pane at a time, setting a new marked pane clears the
1218 last. The marked pane is the default target for -s to join-pane,
1219 swap-pane and swap-window.
1220 select-window [-lnpT] [-t target-window]
1222 (alias: selectw)
1223 Select the window at target-window. -l, -n and -p are equivalent
1224 to the last-window, next-window and previous-window commands. If
1225 -T is given and the selected window is already the current win‐
1226 dow, the command behaves like last-window.
1227 split-window [-bdfhIvP] [-c start-directory] [-e environment] [-l size |
1229 -p percentage] [-t target-pane] [shell-command] [-F format]
1230 (alias: splitw)
1231 Create a new pane by splitting target-pane: -h does a horizontal
1232 split and -v a vertical split; if neither is specified, -v is
1233 assumed. The -l and -p options specify the size of the new pane
1234 in lines (for vertical split) or in cells (for horizontal split),
1235 or as a percentage, respectively. The -b option causes the new
1236 pane to be created to the left of or above target-pane. The -f
1237 option creates a new pane spanning the full window height (with
1238 -h) or full window width (with -v), instead of splitting the
1239 active pane.
1240 An empty shell-command ('') will create a pane with no command
1242 running in it. Output can be sent to such a pane with the
1243 display-message command. The -I flag (if shell-command is not
1244 specified or empty) will create an empty pane and forward any
1245 output from stdin to it. For example:
1246 $ make 2>&1|tmux splitw -dI &
1248 All other options have the same meaning as for the new-window
1250 command.
1251 swap-pane [-dDU] [-s src-pane] [-t dst-pane]
1253 (alias: swapp)
1254 Swap two panes. If -U is used and no source pane is specified
1255 with -s, dst-pane is swapped with the previous pane (before it
1256 numerically); -D swaps with the next pane (after it numerically).
1257 -d instructs tmux not to change the active pane.
1258 If -s is omitted and a marked pane is present (see select-pane
1260 -m), the marked pane is used rather than the current pane.
1261 swap-window [-d] [-s src-window] [-t dst-window]
1263 (alias: swapw)
1264 This is similar to link-window, except the source and destination
1265 windows are swapped. It is an error if no window exists at
1266 src-window.
1267 Like swap-pane, if -s is omitted and a marked pane is present
1269 (see select-pane -m), the window containing the marked pane is
1270 used rather than the current window.
1271 unlink-window [-k] [-t target-window]
1273 (alias: unlinkw)
1274 Unlink target-window. Unless -k is given, a window may be
1275 unlinked only if it is linked to multiple sessions - windows may
1276 not be linked to no sessions; if -k is specified and the window
1277 is linked to only one session, it is unlinked and destroyed.
1278
1280 tmux allows a command to be bound to most keys, with or without a prefix
1281 key. When specifying keys, most represent themselves (for example ‘A’ to
1282 ‘Z’). Ctrl keys may be prefixed with ‘C-’ or ‘^’, and Alt (meta) with
1283 ‘M-’. In addition, the following special key names are accepted: Up,
1284 Down, Left, Right, BSpace, BTab, DC (Delete), End, Enter, Escape, F1 to
1285 F12, Home, IC (Insert), NPage/PageDown/PgDn, PPage/PageUp/PgUp, Space,
1286 and Tab. Note that to bind the ‘"’ or ‘'’ keys, quotation marks are nec‐
1287 essary, for example:
1288 bind-key '"' split-window
1290 bind-key "'" new-window
1291 Commands related to key bindings are as follows:
1293 bind-key [-nr] [-T key-table] key command [arguments]
1295 (alias: bind)
1296 Bind key key to command. Keys are bound in a key table. By
1297 default (without -T), the key is bound in the prefix key table.
1298 This table is used for keys pressed after the prefix key (for
1299 example, by default ‘c’ is bound to new-window in the prefix ta‐
1300 ble, so ‘C-b c’ creates a new window). The root table is used
1301 for keys pressed without the prefix key: binding ‘c’ to
1302 new-window in the root table (not recommended) means a plain ‘c’
1303 will create a new window. -n is an alias for -T root. Keys may
1304 also be bound in custom key tables and the switch-client -T com‐
1305 mand used to switch to them from a key binding. The -r flag
1306 indicates this key may repeat, see the repeat-time option.
1307 To view the default bindings and possible commands, see the
1309 list-keys command.
1310 list-keys [-T key-table]
1312 (alias: lsk)
1313 List all key bindings. Without -T all key tables are printed.
1314 With -T only key-table.
1315 send-keys [-HlMRX] [-N repeat-count] [-t target-pane] key ...
1317 (alias: send)
1318 Send a key or keys to a window. Each argument key is the name of
1319 the key (such as ‘C-a’ or ‘NPage’) to send; if the string is not
1320 recognised as a key, it is sent as a series of characters. All
1321 arguments are sent sequentially from first to last.
1322 The -l flag disables key name lookup and processes the keys as
1324 literal UTF-8 characters. The -H flag expects each key to be a
1325 hexadecimal number for an ASCII character.
1326 The -R flag causes the terminal state to be reset.
1328 -M passes through a mouse event (only valid if bound to a mouse
1330 key binding, see MOUSE SUPPORT).
1331 -X is used to send a command into copy mode - see the WINDOWS AND
1333 PANES section. -N specifies a repeat count.
1334 send-prefix [-2] [-t target-pane]
1336 Send the prefix key, or with -2 the secondary prefix key, to a
1337 window as if it was pressed.
1338 unbind-key [-an] [-T key-table] key
1340 (alias: unbind)
1341 Unbind the command bound to key. -n and -T are the same as for
1342 bind-key. If -a is present, all key bindings are removed.
1343
1345 The appearance and behaviour of tmux may be modified by changing the
1346 value of various options. There are four types of option: server
1347 options, session options window options and pane options.
1348 The tmux server has a set of global options which do not apply to any
1350 particular window or session or pane. These are altered with the
1351 set-option -s command, or displayed with the show-options -s command.
1352 In addition, each individual session may have a set of session options,
1354 and there is a separate set of global session options. Sessions which do
1355 not have a particular option configured inherit the value from the global
1356 session options. Session options are set or unset with the set-option
1357 command and may be listed with the show-options command. The available
1358 server and session options are listed under the set-option command.
1359 Similarly, a set of window options is attached to each window and a set
1361 of pane options to each pane. Pane options inherit from window options.
1362 This means any pane option may be set as a window option to apply the
1363 option to all panes in the window without the option set, for example
1364 these commands will set the background colour to red for all panes except
1365 pane 0:
1366 set -w window-style bg=red
1368 set -pt:.0 window-style bg=blue
1369 There is also a set of global window options from which any unset window
1371 or pane options are inherited. Window and pane options are altered with
1372 set-option -w and -p commands and displayed with show-option -w and -p.
1373 tmux also supports user options which are prefixed with a ‘@’. User
1375 options may have any name, so long as they are prefixed with ‘@’, and be
1376 set to any string. For example:
1377 $ tmux setw -q @foo "abc123"
1379 $ tmux showw -v @foo
1380 abc123
1381 Commands which set options are as follows:
1383 set-option [-aFgopqsuw] [-t target-pane] option value
1385 (alias: set)
1386 Set a pane option with -p, a window option with -w, a server
1387 option with -s, otherwise a session option. If the option is not
1388 a user option, -w or -s may be unnecessary - tmux will infer the
1389 type from the option name, assuming -w for pane options. If -g
1390 is given, the global session or window option is set.
1391 -F expands formats in the option value. The -u flag unsets an
1393 option, so a session inherits the option from the global options
1394 (or with -g, restores a global option to the default).
1395 The -o flag prevents setting an option that is already set and
1397 the -q flag suppresses errors about unknown or ambiguous options.
1398 With -a, and if the option expects a string or a style, value is
1400 appended to the existing setting. For example:
1401 set -g status-left "foo"
1403 set -ag status-left "bar"
1404 Will result in ‘foobar’. And:
1406 set -g status-style "bg=red"
1408 set -ag status-style "fg=blue"
1409 Will result in a red background and blue foreground. Without -a,
1411 the result would be the default background and a blue foreground.
1412 show-options [-AgHpqsvw] [-t target-pane] [option]
1414 (alias: show)
1415 Show the pane options (or a single option if option is provided)
1416 with -p, the window options with -w, the server options with -s,
1417 otherwise the session options. If the option is not a user
1418 option, -w or -s may be unnecessary - tmux will infer the type
1419 from the option name, assuming -w for pane options. Global ses‐
1420 sion or window options are listed if -g is used. -v shows only
1421 the option value, not the name. If -q is set, no error will be
1422 returned if option is unset. -H includes hooks (omitted by
1423 default). -A includes options inherited from a parent set of
1424 options, such options are marked with an asterisk. value depends
1425 on the option and may be a number, a string, or a flag (on, off,
1426 or omitted to toggle).
1427 Available server options are:
1429 buffer-limit number
1431 Set the number of buffers; as new buffers are added to the top of
1432 the stack, old ones are removed from the bottom if necessary to
1433 maintain this maximum length.
1434 command-alias[] name=value
1436 This is an array of custom aliases for commands. If an unknown
1437 command matches name, it is replaced with value. For example,
1438 after:
1439 set -s command-alias[100] zoom='resize-pane -Z'
1441 Using:
1443 zoom -t:.1
1445 Is equivalent to:
1447 resize-pane -Z -t:.1
1449 Note that aliases are expanded when a command is parsed rather
1451 than when it is executed, so binding an alias with bind-key will
1452 bind the expanded form.
1453 default-terminal terminal
1455 Set the default terminal for new windows created in this session
1456 - the default value of the TERM environment variable. For tmux
1457 to work correctly, this must be set to ‘screen’, ‘tmux’ or a de‐
1458 rivative of them.
1459 escape-time time
1461 Set the time in milliseconds for which tmux waits after an escape
1462 is input to determine if it is part of a function or meta key
1463 sequences. The default is 500 milliseconds.
1464 exit-empty [on | off]
1466 If enabled (the default), the server will exit when there are no
1467 active sessions.
1468 exit-unattached [on | off]
1470 If enabled, the server will exit when there are no attached
1471 clients.
1472 focus-events [on | off]
1474 When enabled, focus events are requested from the terminal if
1475 supported and passed through to applications running in tmux.
1476 Attached clients should be detached and attached again after
1477 changing this option.
1478 history-file path
1480 If not empty, a file to which tmux will write command prompt his‐
1481 tory on exit and load it from on start.
1482 message-limit number
1484 Set the number of error or information messages to save in the
1485 message log for each client. The default is 100.
1486 set-clipboard [on | external | off]
1488 Attempt to set the terminal clipboard content using the xterm(1)
1489 escape sequence, if there is an Ms entry in the terminfo(5)
1490 description (see the TERMINFO EXTENSIONS section).
1491 If set to on, tmux will both accept the escape sequence to create
1493 a buffer and attempt to set the terminal clipboard. If set to
1494 external, tmux will attempt to set the terminal clipboard but
1495 ignore attempts by applications to set tmux buffers. If off,
1496 tmux will neither accept the clipboard escape sequence nor
1497 attempt to set the clipboard.
1498 Note that this feature needs to be enabled in xterm(1) by setting
1500 the resource:
1501 disallowedWindowOps: 20,21,SetXprop
1503 Or changing this property from the xterm(1) interactive menu when
1505 required.
1506 terminal-overrides[] string
1508 Allow terminal descriptions read using terminfo(5) to be overrid‐
1509 den. Each entry is a colon-separated string made up of a termi‐
1510 nal type pattern (matched using fnmatch(3)) and a set of
1511 name=value entries.
1512 For example, to set the ‘clear’ terminfo(5) entry to ‘\e[H\e[2J’
1514 for all terminal types matching ‘rxvt*’:
1515 rxvt*:clear=\e[H\e[2J
1517 The terminal entry value is passed through strunvis(3) before
1519 interpretation.
1520 user-keys[] key
1522 Set list of user-defined key escape sequences. Each item is
1523 associated with a key named ‘User0’, ‘User1’, and so on.
1524 For example:
1526 set -s user-keys[0] "\e[5;30012~"
1528 bind User0 resize-pane -L 3
1529 Available session options are:
1531 activity-action [any | none | current | other]
1533 Set action on window activity when monitor-activity is on. any
1534 means activity in any window linked to a session causes a bell or
1535 message (depending on visual-activity) in the current window of
1536 that session, none means all activity is ignored (equivalent to
1537 monitor-activity being off), current means only activity in win‐
1538 dows other than the current window are ignored and other means
1539 activity in the current window is ignored but not those in other
1540 windows.
1541 assume-paste-time milliseconds
1543 If keys are entered faster than one in milliseconds, they are
1544 assumed to have been pasted rather than typed and tmux key bind‐
1545 ings are not processed. The default is one millisecond and zero
1546 disables.
1547 base-index index
1549 Set the base index from which an unused index should be searched
1550 when a new window is created. The default is zero.
1551 bell-action [any | none | current | other]
1553 Set action on a bell in a window when monitor-bell is on. The
1554 values are the same as those for activity-action.
1555 default-command shell-command
1557 Set the command used for new windows (if not specified when the
1558 window is created) to shell-command, which may be any sh(1) com‐
1559 mand. The default is an empty string, which instructs tmux to
1560 create a login shell using the value of the default-shell option.
1561 default-shell path
1563 Specify the default shell. This is used as the login shell for
1564 new windows when the default-command option is set to empty, and
1565 must be the full path of the executable. When started tmux tries
1566 to set a default value from the first suitable of the SHELL envi‐
1567 ronment variable, the shell returned by getpwuid(3), or /bin/sh.
1568 This option should be configured when tmux is used as a login
1569 shell.
1570 default-size XxY
1572 Set the default size of new windows when the window-size option
1573 is set to manual or when a session is created with new-session
1574 -d. The value is the width and height separated by an ‘x’ char‐
1575 acter. The default is 80x24.
1576 destroy-unattached [on | off]
1578 If enabled and the session is no longer attached to any clients,
1579 it is destroyed.
1580 detach-on-destroy [on | off]
1582 If on (the default), the client is detached when the session it
1583 is attached to is destroyed. If off, the client is switched to
1584 the most recently active of the remaining sessions.
1585 display-panes-active-colour colour
1587 Set the colour used by the display-panes command to show the
1588 indicator for the active pane.
1589 display-panes-colour colour
1591 Set the colour used by the display-panes command to show the
1592 indicators for inactive panes.
1593 display-panes-time time
1595 Set the time in milliseconds for which the indicators shown by
1596 the display-panes command appear.
1597 display-time time
1599 Set the amount of time for which status line messages and other
1600 on-screen indicators are displayed. If set to 0, messages and
1601 indicators are displayed until a key is pressed. time is in mil‐
1602 liseconds.
1603 history-limit lines
1605 Set the maximum number of lines held in window history. This
1606 setting applies only to new windows - existing window histories
1607 are not resized and retain the limit at the point they were cre‐
1608 ated.
1609 key-table key-table
1611 Set the default key table to key-table instead of root.
1612 lock-after-time number
1614 Lock the session (like the lock-session command) after number
1615 seconds of inactivity. The default is not to lock (set to 0).
1616 lock-command shell-command
1618 Command to run when locking each client. The default is to run
1619 lock(1) with -np.
1620 message-command-style style
1622 Set status line message command style. For how to specify style,
1623 see the STYLES section.
1624 message-style style
1626 Set status line message style. For how to specify style, see the
1627 STYLES section.
1628 mouse [on | off]
1630 If on, tmux captures the mouse and allows mouse events to be
1631 bound as key bindings. See the MOUSE SUPPORT section for
1632 details.
1633 prefix key
1635 Set the key accepted as a prefix key. In addition to the stan‐
1636 dard keys described under KEY BINDINGS, prefix can be set to the
1637 special key ‘None’ to set no prefix.
1638 prefix2 key
1640 Set a secondary key accepted as a prefix key. Like prefix,
1641 prefix2 can be set to ‘None’.
1642 renumber-windows [on | off]
1644 If on, when a window is closed in a session, automatically renum‐
1645 ber the other windows in numerical order. This respects the
1646 base-index option if it has been set. If off, do not renumber
1647 the windows.
1648 repeat-time time
1650 Allow multiple commands to be entered without pressing the pre‐
1651 fix-key again in the specified time milliseconds (the default is
1652 500). Whether a key repeats may be set when it is bound using
1653 the -r flag to bind-key. Repeat is enabled for the default keys
1654 bound to the resize-pane command.
1655 set-titles [on | off]
1657 Attempt to set the client terminal title using the tsl and fsl
1658 terminfo(5) entries if they exist. tmux automatically sets these
1659 to the \e]0;...\007 sequence if the terminal appears to be
1660 xterm(1). This option is off by default.
1661 set-titles-string string
1663 String used to set the client terminal title if set-titles is on.
1664 Formats are expanded, see the FORMATS section.
1665 silence-action [any | none | current | other]
1667 Set action on window silence when monitor-silence is on. The
1668 values are the same as those for activity-action.
1669 status [off | on | 2 | 3 | 4 | 5]
1671 Show or hide the status line or specify its size. Using on gives
1672 a status line one row in height; 2, 3, 4 or 5 more rows.
1673 status-format[] format
1675 Specify the format to be used for each line of the status line.
1676 The default builds the top status line from the various individ‐
1677 ual status options below.
1678 status-interval interval
1680 Update the status line every interval seconds. By default,
1681 updates will occur every 15 seconds. A setting of zero disables
1682 redrawing at interval.
1683 status-justify [left | centre | right]
1685 Set the position of the window list component of the status line:
1686 left, centre or right justified.
1687 status-keys [vi | emacs]
1689 Use vi or emacs-style key bindings in the status line, for exam‐
1690 ple at the command prompt. The default is emacs, unless the
1691 VISUAL or EDITOR environment variables are set and contain the
1692 string ‘vi’.
1693 status-left string
1695 Display string (by default the session name) to the left of the
1696 status line. string will be passed through strftime(3). Also
1697 see the FORMATS and STYLES sections.
1698 For details on how the names and titles can be set see the NAMES
1700 AND TITLES section.
1701 Examples are:
1703 #(sysctl vm.loadavg)
1705 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
1706 The default is ‘[#S] ’.
1708 status-left-length length
1710 Set the maximum length of the left component of the status line.
1711 The default is 10.
1712 status-left-style style
1714 Set the style of the left part of the status line. For how to
1715 specify style, see the STYLES section.
1716 status-position [top | bottom]
1718 Set the position of the status line.
1719 status-right string
1721 Display string to the right of the status line. By default, the
1722 current pane title in double quotes, the date and the time are
1723 shown. As with status-left, string will be passed to strftime(3)
1724 and character pairs are replaced.
1725 status-right-length length
1727 Set the maximum length of the right component of the status line.
1728 The default is 40.
1729 status-right-style style
1731 Set the style of the right part of the status line. For how to
1732 specify style, see the STYLES section.
1733 status-style style
1735 Set status line style. For how to specify style, see the STYLES
1736 section.
1737 update-environment[] variable
1739 Set list of environment variables to be copied into the session
1740 environment when a new session is created or an existing session
1741 is attached. Any variables that do not exist in the source envi‐
1742 ronment are set to be removed from the session environment (as if
1743 -r was given to the set-environment command).
1744 visual-activity [on | off | both]
1746 If on, display a message instead of sending a bell when activity
1747 occurs in a window for which the monitor-activity window option
1748 is enabled. If set to both, a bell and a message are produced.
1749 visual-bell [on | off | both]
1751 If on, a message is shown on a bell in a window for which the
1752 monitor-bell window option is enabled instead of it being passed
1753 through to the terminal (which normally makes a sound). If set
1754 to both, a bell and a message are produced. Also see the
1755 bell-action option.
1756 visual-silence [on | off | both]
1758 If monitor-silence is enabled, prints a message after the inter‐
1759 val has expired on a given window instead of sending a bell. If
1760 set to both, a bell and a message are produced.
1761 word-separators string
1763 Sets the session's conception of what characters are considered
1764 word separators, for the purposes of the next and previous word
1765 commands in copy mode. The default is ‘ -_@’.
1766 Available window options are:
1768 aggressive-resize [on | off]
1770 Aggressively resize the chosen window. This means that tmux will
1771 resize the window to the size of the smallest or largest session
1772 (see the window-size option) for which it is the current window,
1773 rather than the session to which it is attached. The window may
1774 resize when the current window is changed on another session;
1775 this option is good for full-screen programs which support
1776 SIGWINCH and poor for interactive programs such as shells.
1777 automatic-rename [on | off]
1779 Control automatic window renaming. When this setting is enabled,
1780 tmux will rename the window automatically using the format speci‐
1781 fied by automatic-rename-format. This flag is automatically dis‐
1782 abled for an individual window when a name is specified at cre‐
1783 ation with new-window or new-session, or later with
1784 rename-window, or with a terminal escape sequence. It may be
1785 switched off globally with:
1786 set-option -wg automatic-rename off
1788 automatic-rename-format format
1790 The format (see FORMATS) used when the automatic-rename option is
1791 enabled.
1792 clock-mode-colour colour
1794 Set clock colour.
1795 clock-mode-style [12 | 24]
1797 Set clock hour format.
1798 main-pane-height height
1800 main-pane-width width
1801 Set the width or height of the main (left or top) pane in the
1802 main-horizontal or main-vertical layouts.
1803 mode-keys [vi | emacs]
1805 Use vi or emacs-style key bindings in copy mode. The default is
1806 emacs, unless VISUAL or EDITOR contains ‘vi’.
1807 mode-style style
1809 Set window modes style. For how to specify style, see the STYLES
1810 section.
1811 monitor-activity [on | off]
1813 Monitor for activity in the window. Windows with activity are
1814 highlighted in the status line.
1815 monitor-bell [on | off]
1817 Monitor for a bell in the window. Windows with a bell are high‐
1818 lighted in the status line.
1819 monitor-silence [interval]
1821 Monitor for silence (no activity) in the window within interval
1822 seconds. Windows that have been silent for the interval are
1823 highlighted in the status line. An interval of zero disables the
1824 monitoring.
1825 other-pane-height height
1827 Set the height of the other panes (not the main pane) in the
1828 main-horizontal layout. If this option is set to 0 (the
1829 default), it will have no effect. If both the main-pane-height
1830 and other-pane-height options are set, the main pane will grow
1831 taller to make the other panes the specified height, but will
1832 never shrink to do so.
1833 other-pane-width width
1835 Like other-pane-height, but set the width of other panes in the
1836 main-vertical layout.
1837 pane-active-border-style style
1839 Set the pane border style for the currently active pane. For how
1840 to specify style, see the STYLES section. Attributes are
1841 ignored.
1842 pane-base-index index
1844 Like base-index, but set the starting index for pane numbers.
1845 pane-border-format format
1847 Set the text shown in pane border status lines.
1848 pane-border-status [off | top | bottom]
1850 Turn pane border status lines off or set their position.
1851 pane-border-style style
1853 Set the pane border style for panes aside from the active pane.
1854 For how to specify style, see the STYLES section. Attributes are
1855 ignored.
1856 synchronize-panes [on | off]
1858 Duplicate input to any pane to all other panes in the same window
1859 (only for panes that are not in any special mode).
1860 window-status-activity-style style
1862 Set status line style for windows with an activity alert. For
1863 how to specify style, see the STYLES section.
1864 window-status-bell-style style
1866 Set status line style for windows with a bell alert. For how to
1867 specify style, see the STYLES section.
1868 window-status-current-format string
1870 Like window-status-format, but is the format used when the window
1871 is the current window.
1872 window-status-current-style style
1874 Set status line style for the currently active window. For how
1875 to specify style, see the STYLES section.
1876 window-status-format string
1878 Set the format in which the window is displayed in the status
1879 line window list. See the FORMATS and STYLES sections.
1880 window-status-last-style style
1882 Set status line style for the last active window. For how to
1883 specify style, see the STYLES section.
1884 window-status-separator string
1886 Sets the separator drawn between windows in the status line. The
1887 default is a single space character.
1888 window-status-style style
1890 Set status line style for a single window. For how to specify
1891 style, see the STYLES section.
1892 window-size largest | smallest | manual
1894 Configure how tmux determines the window size. If set to
1895 largest, the size of the largest attached session is used; if
1896 smallest, the size of the smallest. If manual, the size of a new
1897 window is set from the default-size option and windows are
1898 resized automatically. See also the resize-window command and
1899 the aggressive-resize option.
1900 wrap-search [on | off]
1902 If this option is set, searches will wrap around the end of the
1903 pane contents. The default is on.
1904 xterm-keys [on | off]
1906 If this option is set, tmux will generate xterm(1) -style func‐
1907 tion key sequences; these have a number included to indicate mod‐
1908 ifiers such as Shift, Alt or Ctrl.
1909 Available pane options are:
1911 allow-rename [on | off]
1913 Allow programs in the pane to change the window name using a ter‐
1914 minal escape sequence (\ek...\e\\).
1915 alternate-screen [on | off]
1917 This option configures whether programs running inside the pane
1918 may use the terminal alternate screen feature, which allows the
1919 smcup and rmcup terminfo(5) capabilities. The alternate screen
1920 feature preserves the contents of the window when an interactive
1921 application starts and restores it on exit, so that any output
1922 visible before the application starts reappears unchanged after
1923 it exits.
1924 remain-on-exit [on | off]
1926 A pane with this flag set is not destroyed when the program run‐
1927 ning in it exits. The pane may be reactivated with the
1928 respawn-pane command.
1929 window-active-style style
1931 Set the pane style when it is the active pane. For how to spec‐
1932 ify style, see the STYLES section.
1933 window-style style
1935 Set the pane style. For how to specify style, see the STYLES
1936 section.
1937
1939 tmux allows commands to run on various triggers, called hooks. Most tmux
1940 commands have an after hook and there are a number of hooks not associ‐
1941 ated with commands.
1942 Hooks are stored as array options, members of the array are executed in
1944 order when the hook is triggered. Hooks may be configured with the
1945 set-hook or set-option commands and displayed with show-hooks or
1946 show-options -H. The following two commands are equivalent:
1947 set-hook -g pane-mode-changed[42] 'set -g status-left-style bg=red'
1949 set-option -g pane-mode-changed[42] 'set -g status-left-style bg=red'
1950 Setting a hook without specifying an array index clears the hook and sets
1952 the first member of the array.
1953 A command's after hook is run after it completes, except when the command
1955 is run as part of a hook itself. They are named with an ‘after-’ prefix.
1956 For example, the following command adds a hook to select the even-verti‐
1957 cal layout after every split-window:
1958 set-hook -g after-split-window "selectl even-vertical"
1960 All the notifications listed in the CONTROL MODE section are hooks (with‐
1962 out any arguments), except %exit. The following additional hooks are
1963 available:
1964 alert-activity Run when a window has activity. See
1966 monitor-activity.
1967 alert-bell Run when a window has received a bell. See
1969 monitor-bell.
1970 alert-silence Run when a window has been silent. See
1972 monitor-silence.
1973 client-attached Run when a client is attached.
1975 client-detached Run when a client is detached
1977 client-resized Run when a client is resized.
1979 client-session-changed Run when a client's attached session is changed.
1981 pane-died Run when the program running in a pane exits, but
1983 remain-on-exit is on so the pane has not closed.
1984 pane-exited Run when the program running in a pane exits.
1986 pane-focus-in Run when the focus enters a pane, if the
1988 focus-events option is on.
1989 pane-focus-out Run when the focus exits a pane, if the
1991 focus-events option is on.
1992 pane-set-clipboard Run when the terminal clipboard is set using the
1994 xterm(1) escape sequence.
1995 session-created Run when a new session created.
1997 session-closed Run when a session closed.
1999 session-renamed Run when a session is renamed.
2001 window-linked Run when a window is linked into a session.
2003 window-renamed Run when a window is renamed.
2005 window-unlinked Run when a window is unlinked from a session.
2007 Hooks are managed with these commands:
2009 set-hook [-agRu] [-t target-session] hook-name command
2011 Without -R, sets (or with -u unsets) hook hook-name to command.
2012 If -g is given, hook-name is added to the global list of hooks,
2013 otherwise it is added to the session hooks (for target-session
2014 with -t). -a appends to a hook. Like options, session hooks
2015 inherit from the global ones.
2016 With -R, run hook-name immediately.
2018 show-hooks [-g] [-t target-session]
2020 Shows the global list of hooks with -g, otherwise the session
2021 hooks.
2022
2024 If the mouse option is on (the default is off), tmux allows mouse events
2025 to be bound as keys. The name of each key is made up of a mouse event
2026 (such as ‘MouseUp1’) and a location suffix, one of the following:
2027 Pane the contents of a pane
2029 Border a pane border
2030 Status the status line window list
2031 StatusLeft the left part of the status line
2032 StatusRight the right part of the status line
2033 StatusDefault any other part of the status line
2034 The following mouse events are available:
2036 WheelUp WheelDown
2038 MouseDown1 MouseUp1 MouseDrag1 MouseDragEnd1
2039 MouseDown2 MouseUp2 MouseDrag2 MouseDragEnd2
2040 MouseDown3 MouseUp3 MouseDrag3 MouseDragEnd3
2041 DoubleClick1 DoubleClick2 DoubleClick3
2042 TripleClick1 TripleClick2 TripleClick3
2043 Each should be suffixed with a location, for example ‘MouseDown1Status’.
2045 The special token ‘{mouse}’ or ‘=’ may be used as target-window or
2047 target-pane in commands bound to mouse key bindings. It resolves to the
2048 window or pane over which the mouse event took place (for example, the
2049 window in the status line over which button 1 was released for a
2050 ‘MouseUp1Status’ binding, or the pane over which the wheel was scrolled
2051 for a ‘WheelDownPane’ binding).
2052 The send-keys -M flag may be used to forward a mouse event to a pane.
2054 The default key bindings allow the mouse to be used to select and resize
2056 panes, to copy text and to change window using the status line. These
2057 take effect if the mouse option is turned on.
2058
2060 Certain commands accept the -F flag with a format argument. This is a
2061 string which controls the output format of the command. Format variables
2062 are enclosed in ‘#{’ and ‘}’, for example ‘#{session_name}’. The possi‐
2063 ble variables are listed in the table below, or the name of a tmux option
2064 may be used for an option's value. Some variables have a shorter alias
2065 such as ‘#S’; ‘##’ is replaced by a single ‘#’, ‘#,’ by a ‘,’ and ‘#}’ by
2066 a ‘}’.
2067 Conditionals are available by prefixing with ‘?’ and separating two
2069 alternatives with a comma; if the specified variable exists and is not
2070 zero, the first alternative is chosen, otherwise the second is used. For
2071 example ‘#{?session_attached,attached,not attached}’ will include the
2072 string ‘attached’ if the session is attached and the string ‘not
2073 attached’ if it is unattached, or ‘#{?automatic-rename,yes,no}’ will
2074 include ‘yes’ if automatic-rename is enabled, or ‘no’ if not. Condition‐
2075 als can be nested arbitrarily. Inside a conditional, ‘,’ and ‘}’ must be
2076 escaped as ‘#,’ and ‘#}’, unless they are part of a ‘#{...}’ replacement.
2077 For example:
2078 #{?pane_in_mode,#[fg=white#,bg=red],#[fg=red#,bg=white]}#W .
2080 String comparisons may be expressed by prefixing two comma-separated
2082 alternatives by ‘==’, ‘!=’, ‘<’, ‘>’, ‘<=’ or ‘>=’ and a colon. For
2083 example ‘#{==:#{host},myhost}’ will be replaced by ‘1’ if running on
2084 ‘myhost’, otherwise by ‘0’. ‘||’ and ‘&&’ evaluate to true if either or
2085 both of two comma-separated alternatives are true, for example
2086 ‘#{||:#{pane_in_mode},#{alternate_on}}’.
2087 An ‘m’ specifies an fnmatch(3) or regular expression comparison. The
2089 first argument is the pattern and the second the string to compare. An
2090 optional third argument specifies flags: ‘r’ means the pattern is a regu‐
2091 lar expression instead of the default fnmatch(3) pattern, and ‘i’ means
2092 to ignore case. For example: ‘#{m:*foo*,#{host}}’ or ‘#{m/ri:^A,MYVAR}’.
2093 A ‘C’ performs a search for an fnmatch(3) pattern or regular expression
2094 in the pane content and evaluates to zero if not found, or a line number
2095 if found. Like ‘m’, an ‘r’ flag means search for a regular expression
2096 and ‘i’ ignores case. For example: ‘#{C/r:^Start}’
2097 A limit may be placed on the length of the resultant string by prefixing
2099 it by an ‘=’, a number and a colon. Positive numbers count from the
2100 start of the string and negative from the end, so ‘#{=5:pane_title}’ will
2101 include at most the first five characters of the pane title, or
2102 ‘#{=-5:pane_title}’ the last five characters. A suffix or prefix may be
2103 given as a second argument - if provided then it is appended or prepended
2104 to the string if the length has been trimmed, for example
2105 ‘#{=/5/...:pane_title}’ will append ‘...’ if the pane title is more than
2106 five characters.
2107 Prefixing a time variable with ‘t:’ will convert it to a string, so if
2109 ‘#{window_activity}’ gives ‘1445765102’, ‘#{t:window_activity}’ gives
2110 ‘Sun Oct 25 09:25:02 2015’. The ‘b:’ and ‘d:’ prefixes are basename(3)
2111 and dirname(3) of the variable respectively. ‘q:’ will escape sh(1) spe‐
2112 cial characters. ‘E:’ will expand the format twice, for example
2113 ‘#{E:status-left}’ is the result of expanding the content of the
2114 status-left option rather than the option itself. ‘T:’ is like ‘E:’ but
2115 also expands strftime(3) specifiers. ‘S:’, ‘W:’ or ‘P:’ will loop over
2116 each session, window or pane and insert the format once for each. For
2117 windows and panes, two comma-separated formats may be given: the second
2118 is used for the current window or active pane. For example, to get a
2119 list of windows formatted like the status line:
2120 #{W:#{E:window-status-format} ,#{E:window-status-current-format} }
2122 A prefix of the form ‘s/foo/bar/:’ will substitute ‘foo’ with ‘bar’
2124 throughout. The first argument may be an extended regular expression and
2125 a final argument may be ‘i’ to ignore case, for example ‘s/a(.)/\1x/i:’
2126 would change ‘abABab’ into ‘bxBxbx’.
2127 In addition, the last line of a shell command's output may be inserted
2129 using ‘#()’. For example, ‘#(uptime)’ will insert the system's uptime.
2130 When constructing formats, tmux does not wait for ‘#()’ commands to fin‐
2131 ish; instead, the previous result from running the same command is used,
2132 or a placeholder if the command has not been run before. If the command
2133 hasn't exited, the most recent line of output will be used, but the sta‐
2134 tus line will not be updated more than once a second. Commands are exe‐
2135 cuted with the tmux global environment set (see the GLOBAL AND SESSION
2136 ENVIRONMENT section).
2137 An ‘l’ specifies that a string should be interpreted literally and not
2139 expanded. For example ‘#{l:#{?pane_in_mode,yes,no}}’ will be replaced by
2140 ‘#{?pane_in_mode,yes,no}’.
2141 The following variables are available, where appropriate:
2143 Variable name Alias Replaced with
2145 alternate_on 1 if pane is in alternate screen
2146 alternate_saved_x Saved cursor X in alternate screen
2147 alternate_saved_y Saved cursor Y in alternate screen
2148 buffer_created Time buffer created
2149 buffer_name Name of buffer
2150 buffer_sample Sample of start of buffer
2151 buffer_size Size of the specified buffer in bytes
2152 client_activity Time client last had activity
2153 client_control_mode 1 if client is in control mode
2154 client_created Time client created
2155 client_discarded Bytes discarded when client behind
2156 client_height Height of client
2157 client_key_table Current key table
2158 client_last_session Name of the client's last session
2159 client_name Name of client
2160 client_pid PID of client process
2161 client_prefix 1 if prefix key has been pressed
2162 client_readonly 1 if client is readonly
2163 client_session Name of the client's session
2164 client_termname Terminal name of client
2165 client_termtype Terminal type of client
2166 client_tty Pseudo terminal of client
2167 client_utf8 1 if client supports utf8
2168 client_width Width of client
2169 client_written Bytes written to client
2170 command Name of command in use, if any
2171 command_list_alias Command alias if listing commands
2172 command_list_name Command name if listing commands
2173 command_list_usage Command usage if listing commands
2174 cursor_character Character at cursor in pane
2175 cursor_flag Pane cursor flag
2176 cursor_x Cursor X position in pane
2177 cursor_y Cursor Y position in pane
2178 history_bytes Number of bytes in window history
2179 history_limit Maximum window history lines
2180 history_size Size of history in lines
2181 hook Name of running hook, if any
2182 hook_pane ID of pane where hook was run, if any
2183 hook_session ID of session where hook was run, if any
2184 hook_session_name Name of session where hook was run, if
2185 any
2186 hook_window ID of window where hook was run, if any
2187 hook_window_name Name of window where hook was run, if any
2188 host #H Hostname of local host
2189 host_short #h Hostname of local host (no domain name)
2190 insert_flag Pane insert flag
2191 keypad_cursor_flag Pane keypad cursor flag
2192 keypad_flag Pane keypad flag
2193 line Line number in the list
2194 mouse_all_flag Pane mouse all flag
2195 mouse_any_flag Pane mouse any flag
2196 mouse_button_flag Pane mouse button flag
2197 mouse_line Line under mouse, if any
2198 mouse_sgr_flag Pane mouse SGR flag
2199 mouse_standard_flag Pane mouse standard flag
2200 mouse_utf8_flag Pane mouse UTF-8 flag
2201 mouse_word Word under mouse, if any
2202 mouse_x Mouse X position, if any
2203 mouse_y Mouse Y position, if any
2204 origin_flag Pane origin flag
2205 pane_active 1 if active pane
2206 pane_at_bottom 1 if pane is at the bottom of window
2207 pane_at_left 1 if pane is at the left of window
2208 pane_at_right 1 if pane is at the right of window
2209 pane_at_top 1 if pane is at the top of window
2210 pane_bottom Bottom of pane
2211 pane_current_command Current command if available
2212 pane_current_path Current path if available
2213 pane_dead 1 if pane is dead
2214 pane_dead_status Exit status of process in dead pane
2215 pane_format 1 if format is for a pane (not assuming
2216 the current)
2217 pane_height Height of pane
2218 pane_id #D Unique pane ID
2219 pane_in_mode 1 if pane is in a mode
2220 pane_index #P Index of pane
2221 pane_input_off 1 if input to pane is disabled
2222 pane_left Left of pane
2223 pane_marked 1 if this is the marked pane
2224 pane_marked_set 1 if a marked pane is set
2225 pane_mode Name of pane mode, if any
2226 pane_pid PID of first process in pane
2227 pane_pipe 1 if pane is being piped
2228 pane_right Right of pane
2229 pane_search_string Last search string in copy mode
2230 pane_start_command Command pane started with
2231 pane_synchronized 1 if pane is synchronized
2232 pane_tabs Pane tab positions
2233 pane_title #T Title of pane
2234 pane_top Top of pane
2235 pane_tty Pseudo terminal of pane
2236 pane_width Width of pane
2237 pid Server PID
2238 rectangle_toggle 1 if rectangle selection is activated
2239 scroll_position Scroll position in copy mode
2240 scroll_region_lower Bottom of scroll region in pane
2241 scroll_region_upper Top of scroll region in pane
2242 selection_present 1 if selection started in copy mode
2243 session_activity Time of session last activity
2244 session_alerts List of window indexes with alerts
2245 session_attached Number of clients session is attached to
2246 session_created Time session created
2247 session_format 1 if format is for a session (not
2248 assuming the current)
2249 session_group Name of session group
2250 session_group_list List of sessions in group
2251 session_group_size Size of session group
2252 session_grouped 1 if session in a group
2253 session_id Unique session ID
2254 session_last_attached Time session last attached
2255 session_many_attached 1 if multiple clients attached
2256 session_name #S Name of session
2257 session_stack Window indexes in most recent order
2258 session_windows Number of windows in session
2259 socket_path Server socket path
2260 start_time Server start time
2261 version Server version
2262 window_active 1 if window active
2263 window_activity Time of window last activity
2264 window_activity_flag 1 if window has activity
2265 window_bell_flag 1 if window has bell
2266 window_bigger 1 if window is larger than client
2267 window_end_flag 1 if window has the highest index
2268 window_flags #F Window flags
2269 window_format 1 if format is for a window (not assuming
2270 the current)
2271 window_height Height of window
2272 window_id Unique window ID
2273 window_index #I Index of window
2274 window_last_flag 1 if window is the last used
2275 window_layout Window layout description, ignoring
2276 zoomed window panes
2277 window_linked 1 if window is linked across sessions
2278 window_name #W Name of window
2279 window_offset_x X offset into window if larger than
2280 client
2281 window_offset_y Y offset into window if larger than
2282 client
2283 window_panes Number of panes in window
2284 window_silence_flag 1 if window has silence alert
2285 window_stack_index Index in session most recent stack
2286 window_start_flag 1 if window has the lowest index
2287 window_visible_layout Window layout description, respecting
2288 zoomed window panes
2289 window_width Width of window
2290 window_zoomed_flag 1 if window is zoomed
2291 wrap_flag Pane wrap flag
2292
2294 tmux offers various options to specify the colour and attributes of
2295 aspects of the interface, for example status-style for the status line.
2296 In addition, embedded styles may be specified in format options, such as
2297 status-left-format, by enclosing them in ‘#[’ and ‘]’.
2298 A style may be the single term ‘default’ to specify the default style
2300 (which may inherit from another option) or a space or comma separated
2301 list of the following:
2302 fg=colour
2304 Set the foreground colour. The colour is one of: black, red,
2305 green, yellow, blue, magenta, cyan, white; if supported the
2306 bright variants brightred, brightgreen, brightyellow; colour0 to
2307 colour255 from the 256-colour set; default for the default
2308 colour; terminal for the terminal default colour; or a hexadeci‐
2309 mal RGB string such as ‘#ffffff’.
2310 bg=colour
2312 Set the background colour.
2313 none Set no attributes (turn off any active attributes).
2315 bright (or bold), dim, underscore, blink, reverse, hidden, italics,
2317 overline, strikethrough, double-underscore, curly-underscore,
2318 dotted-underscore, dashed-underscore
2319 Set an attribute. Any of the attributes may be prefixed with
2320 ‘no’ to unset.
2321 align=left (or noalign), align=centre, align=right
2323 Align text to the left, centre or right of the available space if
2324 appropriate.
2325 fill=colour
2327 Fill the available space with a background colour if appropriate.
2328 list=on, list=focus, list=left-marker, list=right-marker, nolist
2330 Mark the position of the various window list components in the
2331 status-format option: list=on marks the start of the list;
2332 list=focus is the part of the list that should be kept in focus
2333 if the entire list won't fit in the available space (typically
2334 the current window); list=left-marker and list=right-marker mark
2335 the text to be used to mark that text has been trimmed from the
2336 left or right of the list if there is not enough space.
2337 range=left, range=right, range=window|X, norange
2339 Mark a range in the status-format option. range=left and
2340 range=right are the text used for the ‘StatusLeft’ and
2341 ‘StatusRight’ mouse keys. range=window|X is the range for a win‐
2342 dow passed to the ‘Status’ mouse key, where ‘X’ is a window
2343 index.
2344 Examples are:
2346 fg=yellow bold underscore blink
2348 bg=black,fg=default,noreverse
2349
2351 tmux distinguishes between names and titles. Windows and sessions have
2352 names, which may be used to specify them in targets and are displayed in
2353 the status line and various lists: the name is the tmux identifier for a
2354 window or session. Only panes have titles. A pane's title is typically
2355 set by the program running inside the pane using an escape sequence (like
2356 it would set the xterm(1) window title in X(7)). Windows themselves do
2357 not have titles - a window's title is the title of its active pane. tmux
2358 itself may set the title of the terminal in which the client is running,
2359 see the set-titles option.
2360 A session's name is set with the new-session and rename-session commands.
2362 A window's name is set with one of:
2363 1. A command argument (such as -n for new-window or new-session).
2365 2. An escape sequence (if the allow-rename option is turned on):
2367 $ printf '\033kWINDOW_NAME\033\\'
2369 3. Automatic renaming, which sets the name to the active command in
2371 the window's active pane. See the automatic-rename option.
2372 When a pane is first created, its title is the hostname. A pane's title
2374 can be set via the title setting escape sequence, for example:
2375 $ printf '\033]2;My Title\033\\'
2377 It can also be modified with the select-pane -T command.
2379
2381 When the server is started, tmux copies the environment into the global
2382 environment; in addition, each session has a session environment. When a
2383 window is created, the session and global environments are merged. If a
2384 variable exists in both, the value from the session environment is used.
2385 The result is the initial environment passed to the new process.
2386 The update-environment session option may be used to update the session
2388 environment from the client when a new session is created or an old reat‐
2389 tached. tmux also initialises the TMUX variable with some internal
2390 information to allow commands to be executed from inside, and the TERM
2391 variable with the correct terminal setting of ‘screen’.
2392 Commands to alter and view the environment are:
2394 set-environment [-gru] [-t target-session] name [value]
2396 (alias: setenv)
2397 Set or unset an environment variable. If -g is used, the change
2398 is made in the global environment; otherwise, it is applied to
2399 the session environment for target-session. The -u flag unsets a
2400 variable. -r indicates the variable is to be removed from the
2401 environment before starting a new process.
2402 show-environment [-gs] [-t target-session] [variable]
2404 (alias: showenv)
2405 Display the environment for target-session or the global environ‐
2406 ment with -g. If variable is omitted, all variables are shown.
2407 Variables removed from the environment are prefixed with ‘-’. If
2408 -s is used, the output is formatted as a set of Bourne shell com‐
2409 mands.
2410
2412 tmux includes an optional status line which is displayed in the bottom
2413 line of each terminal.
2414 By default, the status line is enabled and one line in height (it may be
2416 disabled or made multiple lines with the status session option) and con‐
2417 tains, from left-to-right: the name of the current session in square
2418 brackets; the window list; the title of the active pane in double quotes;
2419 and the time and date.
2420 Each line of the status line is configured with the status-format option.
2422 The default is made of three parts: configurable left and right sections
2423 (which may contain dynamic content such as the time or output from a
2424 shell command, see the status-left, status-left-length, status-right, and
2425 status-right-length options below), and a central window list. By
2426 default, the window list shows the index, name and (if any) flag of the
2427 windows present in the current session in ascending numerical order. It
2428 may be customised with the window-status-format and
2429 window-status-current-format options. The flag is one of the following
2430 symbols appended to the window name:
2431 Symbol Meaning
2433 * Denotes the current window.
2434 - Marks the last window (previously selected).
2435 # Window activity is monitored and activity has been
2436 detected.
2437 ! Window bells are monitored and a bell has occurred in the
2438 window.
2439 ~ The window has been silent for the monitor-silence
2440 interval.
2441 M The window contains the marked pane.
2442 Z The window's active pane is zoomed.
2443 The # symbol relates to the monitor-activity window option. The window
2445 name is printed in inverted colours if an alert (bell, activity or
2446 silence) is present.
2447 The colour and attributes of the status line may be configured, the
2449 entire status line using the status-style session option and individual
2450 windows using the window-status-style window option.
2451 The status line is automatically refreshed at interval if it has changed,
2453 the interval may be controlled with the status-interval session option.
2454 Commands related to the status line are as follows:
2456 command-prompt [-1Ni] [-I inputs] [-p prompts] [-t target-client]
2458 [template]
2459 Open the command prompt in a client. This may be used from
2460 inside tmux to execute commands interactively.
2461 If template is specified, it is used as the command. If present,
2463 -I is a comma-separated list of the initial text for each prompt.
2464 If -p is given, prompts is a comma-separated list of prompts
2465 which are displayed in order; otherwise a single prompt is dis‐
2466 played, constructed from template if it is present, or ‘:’ if
2467 not.
2468 Before the command is executed, the first occurrence of the
2470 string ‘%%’ and all occurrences of ‘%1’ are replaced by the
2471 response to the first prompt, all ‘%2’ are replaced with the
2472 response to the second prompt, and so on for further prompts. Up
2473 to nine prompt responses may be replaced (‘%1’ to ‘%9’). ‘%%%’
2474 is like ‘%%’ but any quotation marks are escaped.
2475 -1 makes the prompt only accept one key press, in this case the
2477 resulting input is a single character. -N makes the prompt only
2478 accept numeric key presses. -i executes the command every time
2479 the prompt input changes instead of when the user exits the com‐
2480 mand prompt.
2481 The following keys have a special meaning in the command prompt,
2483 depending on the value of the status-keys option:
2484 Function vi emacs
2486 Cancel command prompt Escape Escape
2487 Delete from cursor to start of word C-w
2488 Delete entire command d C-u
2489 Delete from cursor to end D C-k
2490 Execute command Enter Enter
2491 Get next command from history Down
2492 Get previous command from history Up
2493 Insert top paste buffer p C-y
2494 Look for completions Tab Tab
2495 Move cursor left h Left
2496 Move cursor right l Right
2497 Move cursor to end $ C-e
2498 Move cursor to next word w M-f
2499 Move cursor to previous word b M-b
2500 Move cursor to start 0 C-a
2501 Transpose characters C-t
2502 confirm-before [-p prompt] [-t target-client] command
2504 (alias: confirm)
2505 Ask for confirmation before executing command. If -p is given,
2506 prompt is the prompt to display; otherwise a prompt is con‐
2507 structed from command. It may contain the special character
2508 sequences supported by the status-left option.
2509 This command works only from inside tmux.
2511 display-menu [-c target-client] [-t target-pane] [-T title] [-x position]
2513 [-y position] name key command ...
2514 (alias: menu)
2515 Display a menu on target-client. target-pane gives the target
2516 for any commands run from the menu.
2517 A menu is passed as a series of arguments: first the menu item
2519 name, second the key shortcut (or empty for none) and third the
2520 command to run when the menu item is chosen. The name and com‐
2521 mand are formats, see the FORMATS and STYLES sections. If the
2522 name begins with a hyphen (-), then the item is disabled (shown
2523 dim) and may not be chosen. The name may be empty for a separa‐
2524 tor line, in which case both the key and command should be omit‐
2525 ted.
2526 -T is a format for the menu title (see FORMATS).
2528 -x and -y give the position of the menu. Both may be a row or
2530 column number, or one of the following special values:
2531 Value Flag Meaning
2533 R -x The right side of the terminal
2534 P Both The bottom left of the pane
2535 M Both The mouse position
2536 W -x The window position on the status line
2537 S -y The line above or below the status line
2538 Each menu consists of items followed by a key shortcut shown in
2540 brackets. If the menu is too large to fit on the terminal, it is
2541 not displayed. Pressing the key shortcut chooses the correspond‐
2542 ing item. If the mouse is enabled and the menu is opened from a
2543 mouse key binding, releasing the mouse button with an item
2544 selected will choose that item. The following keys are also
2545 available:
2546 Key Function
2548 Enter Choose selected item
2549 Up Select previous item
2550 Down Select next item
2551 q Exit menu
2552 display-message [-aIpv] [-c target-client] [-t target-pane] [message]
2554 (alias: display)
2555 Display a message. If -p is given, the output is printed to std‐
2556 out, otherwise it is displayed in the target-client status line.
2557 The format of message is described in the FORMATS section; infor‐
2558 mation is taken from target-pane if -t is given, otherwise the
2559 active pane.
2560 -v prints verbose logging as the format is parsed and -a lists
2562 the format variables and their values.
2563 -I forwards any input read from stdin to the empty pane given by
2565 target-pane.
2566
2568 tmux maintains a set of named paste buffers. Each buffer may be either
2569 explicitly or automatically named. Explicitly named buffers are named
2570 when created with the set-buffer or load-buffer commands, or by renaming
2571 an automatically named buffer with set-buffer -n. Automatically named
2572 buffers are given a name such as ‘buffer0001’, ‘buffer0002’ and so on.
2573 When the buffer-limit option is reached, the oldest automatically named
2574 buffer is deleted. Explicitly named buffers are not subject to
2575 buffer-limit and may be deleted with delete-buffer command.
2576 Buffers may be added using copy-mode or the set-buffer and load-buffer
2578 commands, and pasted into a window using the paste-buffer command. If a
2579 buffer command is used and no buffer is specified, the most recently
2580 added automatically named buffer is assumed.
2581 A configurable history buffer is also maintained for each window. By
2583 default, up to 2000 lines are kept; this can be altered with the
2584 history-limit option (see the set-option command above).
2585 The buffer commands are as follows:
2587 choose-buffer [-NZ] [-F format] [-f filter] [-O sort-order] [-t
2589 target-pane] [template]
2590 Put a pane into buffer mode, where a buffer may be chosen inter‐
2591 actively from a list. -Z zooms the pane. The following keys may
2592 be used in buffer mode:
2593 Key Function
2595 Enter Paste selected buffer
2596 Up Select previous buffer
2597 Down Select next buffer
2598 C-s Search by name or content
2599 n Repeat last search
2600 t Toggle if buffer is tagged
2601 T Tag no buffers
2602 C-t Tag all buffers
2603 p Paste selected buffer
2604 P Paste tagged buffers
2605 d Delete selected buffer
2606 D Delete tagged buffers
2607 f Enter a format to filter items
2608 O Change sort order
2609 v Toggle preview
2610 q Exit mode
2611 After a buffer is chosen, ‘%%’ is replaced by the buffer name in
2613 template and the result executed as a command. If template is
2614 not given, "paste-buffer -b '%%'" is used.
2615 -O specifies the initial sort order: one of ‘time’, ‘name’ or
2617 ‘size’. -f specifies an initial filter: the filter is a format -
2618 if it evaluates to zero, the item in the list is not shown, oth‐
2619 erwise it is shown. If a filter would lead to an empty list, it
2620 is ignored. -F specifies the format for each item in the list.
2621 -N starts without the preview. This command works only if at
2622 least one client is attached.
2623 clear-history [-t target-pane]
2625 (alias: clearhist)
2626 Remove and free the history for the specified pane.
2627 delete-buffer [-b buffer-name]
2629 (alias: deleteb)
2630 Delete the buffer named buffer-name, or the most recently added
2631 automatically named buffer if not specified.
2632 list-buffers [-F format]
2634 (alias: lsb)
2635 List the global buffers. For the meaning of the -F flag, see the
2636 FORMATS section.
2637 load-buffer [-b buffer-name] path
2639 (alias: loadb)
2640 Load the contents of the specified paste buffer from path.
2641 paste-buffer [-dpr] [-b buffer-name] [-s separator] [-t target-pane]
2643 (alias: pasteb)
2644 Insert the contents of a paste buffer into the specified pane.
2645 If not specified, paste into the current one. With -d, also
2646 delete the paste buffer. When output, any linefeed (LF) charac‐
2647 ters in the paste buffer are replaced with a separator, by
2648 default carriage return (CR). A custom separator may be speci‐
2649 fied using the -s flag. The -r flag means to do no replacement
2650 (equivalent to a separator of LF). If -p is specified, paste
2651 bracket control codes are inserted around the buffer if the
2652 application has requested bracketed paste mode.
2653 save-buffer [-a] [-b buffer-name] path
2655 (alias: saveb)
2656 Save the contents of the specified paste buffer to path. The -a
2657 option appends to rather than overwriting the file.
2658 set-buffer [-a] [-b buffer-name] [-n new-buffer-name] data
2660 (alias: setb)
2661 Set the contents of the specified buffer to data. The -a option
2662 appends to rather than overwriting the buffer. The -n option
2663 renames the buffer to new-buffer-name.
2664 show-buffer [-b buffer-name]
2666 (alias: showb)
2667 Display the contents of the specified buffer.
2668
2670 Miscellaneous commands are as follows:
2671 clock-mode [-t target-pane]
2673 Display a large clock.
2674 if-shell [-bF] [-t target-pane] shell-command command [command]
2676 (alias: if)
2677 Execute the first command if shell-command returns success or the
2678 second command otherwise. Before being executed, shell-command
2679 is expanded using the rules specified in the FORMATS section,
2680 including those relevant to target-pane. With -b, shell-command
2681 is run in the background.
2682 If -F is given, shell-command is not executed but considered suc‐
2684 cess if neither empty nor zero (after formats are expanded).
2685 lock-server
2687 (alias: lock)
2688 Lock each client individually by running the command specified by
2689 the lock-command option.
2690 run-shell [-b] [-t target-pane] shell-command
2692 (alias: run)
2693 Execute shell-command in the background without creating a win‐
2694 dow. Before being executed, shell-command is expanded using the
2695 rules specified in the FORMATS section. With -b, the command is
2696 run in the background. After it finishes, any output to stdout
2697 is displayed in copy mode (in the pane specified by -t or the
2698 current pane if omitted). If the command doesn't return success,
2699 the exit status is also displayed.
2700 wait-for [-L | -S | -U] channel
2702 (alias: wait)
2703 When used without options, prevents the client from exiting until
2704 woken using wait-for -S with the same channel. When -L is used,
2705 the channel is locked and any clients that try to lock the same
2706 channel are made to wait until the channel is unlocked with
2707 wait-for -U.
2708
2710 tmux understands some unofficial extensions to terminfo(5):
2711 Cs, Cr Set the cursor colour. The first takes a single string argument
2713 and is used to set the colour; the second takes no arguments and
2714 restores the default cursor colour. If set, a sequence such as
2715 this may be used to change the cursor colour from inside tmux:
2716 $ printf '\033]12;red\033\\'
2718 Smol Enable the overline attribute. The capability is usually SGR 53
2720 and can be added to terminal-overrides as:
2721 Smol=\E[53m
2723 Smulx Set a styled underscore. The single parameter is one of: 0 for
2725 no underscore, 1 for normal underscore, 2 for double underscore,
2726 3 for curly underscore, 4 for dotted underscore and 5 for dashed
2727 underscore. The capability can typically be added to
2728 terminal-overrides as:
2729 Smulx=\E[4::%p1%dm
2731 Setulc Set the underscore colour. The argument is (red * 65536) +
2733 (green * 256) + blue where each is between 0 and 255. The capa‐
2734 bility can typically be added to terminal-overrides as:
2735 Setulc=\E[58::2::%p1%{65536}%/%d::%p1%{256}%/%{255}%&%d::%p1%{255}%&%d%;m
2737 Ss, Se Set or reset the cursor style. If set, a sequence such as this
2739 may be used to change the cursor to an underline:
2740 $ printf '\033[4 q'
2742 If Se is not set, Ss with argument 0 will be used to reset the
2744 cursor style instead.
2745 Tc Indicate that the terminal supports the ‘direct colour’ RGB
2747 escape sequence (for example, \e[38;2;255;255;255m).
2748 If supported, this is used for the initialize colour escape
2750 sequence (which may be enabled by adding the ‘initc’ and ‘ccc’
2751 capabilities to the tmux [22mterminfo(5) entry).
2752 Ms Store the current buffer in the host terminal's selection (clip‐
2754 board). See the set-clipboard option above and the xterm(1) man
2755 page.
2756
2758 tmux offers a textual interface called control mode. This allows appli‐
2759 cations to communicate with tmux using a simple text-only protocol.
2760 In control mode, a client sends tmux commands or command sequences termi‐
2762 nated by newlines on standard input. Each command will produce one block
2763 of output on standard output. An output block consists of a %begin line
2764 followed by the output (which may be empty). The output block ends with
2765 a %end or %error. %begin and matching %end or %error have two arguments:
2766 an integer time (as seconds from epoch) and command number. For example:
2767 %begin 1363006971 2
2769 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
2770 %end 1363006971 2
2771 The refresh-client -C command may be used to set the size of a client in
2773 control mode.
2774 In control mode, tmux outputs notifications. A notification will never
2776 occur inside an output block.
2777 The following notifications are defined:
2779 %client-session-changed client session-id name
2781 The client is now attached to the session with ID session-id,
2782 which is named name.
2783 %exit [reason]
2785 The tmux client is exiting immediately, either because it is not
2786 attached to any session or an error occurred. If present, reason
2787 describes why the client exited.
2788 %layout-change window-id window-layout window-visible-layout window-flags
2790 The layout of a window with ID window-id changed. The new layout
2791 is window-layout. The window's visible layout is
2792 window-visible-layout and the window flags are window-flags.
2793 %output pane-id value
2795 A window pane produced output. value escapes non-printable char‐
2796 acters and backslash as octal \xxx.
2797 %pane-mode-changed pane-id
2799 The pane with ID pane-id has changed mode.
2800 %session-changed session-id name
2802 The client is now attached to the session with ID session-id,
2803 which is named name.
2804 %session-renamed name
2806 The current session was renamed to name.
2807 %session-window-changed session-id window-id
2809 The session with ID session-id changed its active window to the
2810 window with ID window-id.
2811 %sessions-changed
2813 A session was created or destroyed.
2814 %unlinked-window-add window-id
2816 The window with ID window-id was created but is not linked to the
2817 current session.
2818 %window-add window-id
2820 The window with ID window-id was linked to the current session.
2821 %window-close window-id
2823 The window with ID window-id closed.
2824 %window-pane-changed window-id pane-id
2826 The active pane in the window with ID window-id changed to the
2827 pane with ID pane-id.
2828 %window-renamed window-id name
2830 The window with ID window-id was renamed to name.
2831
2833 When tmux is started, it inspects the following environment variables:
2834 EDITOR If the command specified in this variable contains the string
2836 ‘vi’ and VISUAL is unset, use vi-style key bindings. Overrid‐
2837 den by the mode-keys and status-keys options.
2838 HOME The user's login directory. If unset, the passwd(5) database
2840 is consulted.
2841 LC_CTYPE The character encoding locale(1). It is used for two separate
2843 purposes. For output to the terminal, UTF-8 is used if the -u
2844 option is given or if LC_CTYPE contains "UTF-8" or "UTF8".
2845 Otherwise, only ASCII characters are written and non-ASCII
2846 characters are replaced with underscores (‘_’). For input,
2847 tmux always runs with a UTF-8 locale. If en_US.UTF-8 is pro‐
2848 vided by the operating system it is used and LC_CTYPE is
2849 ignored for input. Otherwise, LC_CTYPE tells tmux what the
2850 UTF-8 locale is called on the current system. If the locale
2851 specified by LC_CTYPE is not available or is not a UTF-8
2852 locale, tmux exits with an error message.
2853 LC_TIME The date and time format locale(1). It is used for locale-
2855 dependent strftime(3) format specifiers.
2856 PWD The current working directory to be set in the global environ‐
2858 ment. This may be useful if it contains symbolic links. If
2859 the value of the variable does not match the current working
2860 directory, the variable is ignored and the result of getcwd(3)
2861 is used instead.
2862 SHELL The absolute path to the default shell for new windows. See
2864 the default-shell option for details.
2865 TMUX_TMPDIR
2867 The parent directory of the directory containing the server
2868 sockets. See the -L option for details.
2869 VISUAL If the command specified in this variable contains the string
2871 ‘vi’, use vi-style key bindings. Overridden by the mode-keys
2872 and status-keys options.
2873
2875 ~/.tmux.conf Default tmux configuration file.
2876 /etc/tmux.conf System-wide configuration file.
2877
2879 To create a new tmux session running vi(1):
2880 $ tmux new-session vi
2882 Most commands have a shorter form, known as an alias. For new-session,
2884 this is new:
2885 $ tmux new vi
2887 Alternatively, the shortest unambiguous form of a command is accepted.
2889 If there are several options, they are listed:
2890 $ tmux n
2892 ambiguous command: n, could be: new-session, new-window, next-window
2893 Within an active session, a new window may be created by typing ‘C-b c’
2895 (Ctrl followed by the ‘b’ key followed by the ‘c’ key).
2896 Windows may be navigated with: ‘C-b 0’ (to select window 0), ‘C-b 1’ (to
2898 select window 1), and so on; ‘C-b n’ to select the next window; and ‘C-b
2899 p’ to select the previous window.
2900 A session may be detached using ‘C-b d’ (or by an external event such as
2902 ssh(1) disconnection) and reattached with:
2903 $ tmux attach-session
2905 Typing ‘C-b ?’ lists the current key bindings in the current window; up
2907 and down may be used to navigate the list or ‘q’ to exit from it.
2908 Commands to be run when the tmux server is started may be placed in the
2910 ~/.tmux.conf configuration file. Common examples include:
2911 Changing the default prefix key:
2913 set-option -g prefix C-a
2915 unbind-key C-b
2916 bind-key C-a send-prefix
2917 Turning the status line off, or changing its colour:
2919 set-option -g status off
2921 set-option -g status-style bg=blue
2922 Setting other options, such as the default command, or locking after 30
2924 minutes of inactivity:
2925 set-option -g default-command "exec /bin/ksh"
2927 set-option -g lock-after-time 1800
2928 Creating new key bindings:
2930 bind-key b set-option status
2932 bind-key / command-prompt "split-window 'exec man %%'"
2933 bind-key S command-prompt "new-window -n %1 'ssh %1'"
2934
2936 pty(4)
2937
2939 Nicholas Marriott <nicholas.marriott@gmail.com>
2940BSD May 10, 2020 BSD