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 When starting, tmux looks for the LC_ALL, LC_CTYPE and LANG
89 environment variables: if the first found contains ‘UTF-8’,
90 then the terminal is assumed to support UTF-8. This is not
91 always correct: the -u flag explicitly informs tmux that
92 UTF-8 is supported.
93 Note that tmux itself always accepts UTF-8; this controls
95 whether it will send UTF-8 characters to the terminal it is
96 running (if not, they are replaced by ‘_’).
97 -v Request verbose logging. Log messages will be saved into
99 tmux-client-PID.log and tmux-server-PID.log files in the
100 current directory, where PID is the PID of the server or
101 client process. If -v is specified twice, an additional
102 tmux-out-PID.log file is generated with a copy of every‐
103 thing tmux writes to the terminal.
104 The SIGUSR2 signal may be sent to the tmux server process
106 to toggle logging between on (as if -v was given) and off.
107 -V Report the tmux version.
109 command [flags]
111 This specifies one of a set of commands used to control
112 tmux, as described in the following sections. If no com‐
113 mands are specified, the new-session command is assumed.
114
116 tmux may be controlled from an attached client by using a key combination
117 of a prefix key, ‘C-b’ (Ctrl-b) by default, followed by a command key.
118 The default command key bindings are:
120 C-b Send the prefix key (C-b) through to the application.
122 C-o Rotate the panes in the current window forwards.
123 C-z Suspend the tmux client.
124 ! Break the current pane out of the window.
125 " Split the current pane into two, top and bottom.
126 # List all paste buffers.
127 $ Rename the current session.
128 % Split the current pane into two, left and right.
129 & Kill the current window.
130 ' Prompt for a window index to select.
131 ( Switch the attached client to the previous session.
132 ) Switch the attached client to the next session.
133 , Rename the current window.
134 - Delete the most recently copied buffer of text.
135 . Prompt for an index to move the current window.
136 0 to 9 Select windows 0 to 9.
137 : Enter the tmux command prompt.
138 ; Move to the previously active pane.
139 = Choose which buffer to paste interactively from a list.
140 ? List all key bindings.
141 D Choose a client to detach.
142 L Switch the attached client back to the last session.
143 [ Enter copy mode to copy text or view the history.
144 ] Paste the most recently copied buffer of text.
145 c Create a new window.
146 d Detach the current client.
147 f Prompt to search for text in open windows.
148 i Display some information about the current window.
149 l Move to the previously selected window.
150 n Change to the next window.
151 o Select the next pane in the current window.
152 p Change to the previous window.
153 q Briefly display pane indexes.
154 r Force redraw of the attached client.
155 m Mark the current pane (see select-pane -m).
156 M Clear the marked pane.
157 s Select a new session for the attached client interac‐
158 tively.
159 t Show the time.
160 w Choose the current window interactively.
161 x Kill the current pane.
162 z Toggle zoom state of the current pane.
163 { Swap the current pane with the previous pane.
164 } Swap the current pane with the next pane.
165 ~ Show previous messages from tmux, if any.
166 Page Up Enter copy mode and scroll one page up.
167 Up, Down
168 Left, Right
169 Change to the pane above, below, to the left, or to the
170 right of the current pane.
171 M-1 to M-5 Arrange panes in one of the five preset layouts: even-
172 horizontal, even-vertical, main-horizontal, main-verti‐
173 cal, or tiled.
174 Space Arrange the current window in the next preset layout.
175 M-n Move to the next window with a bell or activity marker.
176 M-o Rotate the panes in the current window backwards.
177 M-p Move to the previous window with a bell or activity
178 marker.
179 C-Up, C-Down
180 C-Left, C-Right
181 Resize the current pane in steps of one cell.
182 M-Up, M-Down
183 M-Left, M-Right
184 Resize the current pane in steps of five cells.
185 Key bindings may be changed with the bind-key and unbind-key commands.
187
189 This section contains a list of the commands supported by tmux. Most
190 commands accept the optional -t (and sometimes -s) argument with one of
191 target-client, target-session target-window, or target-pane. These spec‐
192 ify the client, session, window or pane which a command should affect.
193 target-client should be the name of the client, typically the pty(4) file
195 to which the client is connected, for example either of /dev/ttyp1 or
196 ttyp1 for the client attached to /dev/ttyp1. If no client is specified,
197 tmux attempts to work out the client currently in use; if that fails, an
198 error is reported. Clients may be listed with the list-clients command.
199 target-session is tried as, in order:
201 1. A session ID prefixed with a $.
203 2. An exact name of a session (as listed by the list-sessions
205 command).
206 3. The start of a session name, for example ‘mysess’ would match
208 a session named ‘mysession’.
209 4. An fnmatch(3) pattern which is matched against the session
211 name.
212 If the session name is prefixed with an ‘=’, only an exact match is
214 accepted (so ‘=mysess’ will only match exactly ‘mysess’, not
215 ‘mysession’).
216 If a single session is found, it is used as the target session; multiple
218 matches produce an error. If a session is omitted, the current session
219 is used if available; if no current session is available, the most
220 recently used is chosen.
221 target-window (or src-window or dst-window) specifies a window in the
223 form session:window. session follows the same rules as for
224 target-session, and window is looked for in order as:
225 1. A special token, listed below.
227 2. A window index, for example ‘mysession:1’ is window 1 in ses‐
229 sion ‘mysession’.
230 3. A window ID, such as @1.
232 4. An exact window name, such as ‘mysession:mywindow’.
234 5. The start of a window name, such as ‘mysession:mywin’.
236 6. As an fnmatch(3) pattern matched against the window name.
238 Like sessions, a ‘=’ prefix will do an exact match only. An empty window
240 name specifies the next unused index if appropriate (for example the
241 new-window and link-window commands) otherwise the current window in
242 session is chosen.
243 The following special tokens are available to indicate particular win‐
245 dows. Each has a single-character alternative form.
246 Token Meaning
248 {start} ^ The lowest-numbered window
249 {end} $ The highest-numbered window
250 {last} ! The last (previously current) window
251 {next} + The next window by number
252 {previous} - The previous window by number
253 target-pane (or src-pane or dst-pane) may be a pane ID or takes a similar
255 form to target-window but with the optional addition of a period followed
256 by a pane index or pane ID, for example: ‘mysession:mywindow.1’. If the
257 pane index is omitted, the currently active pane in the specified window
258 is used. The following special tokens are available for the pane index:
259 Token Meaning
261 {last} ! The last (previously active) pane
262 {next} + The next pane by number
263 {previous} - The previous pane by number
264 {top} The top pane
265 {bottom} The bottom pane
266 {left} The leftmost pane
267 {right} The rightmost pane
268 {top-left} The top-left pane
269 {top-right} The top-right pane
270 {bottom-left} The bottom-left pane
271 {bottom-right} The bottom-right pane
272 {up-of} The pane above the active pane
273 {down-of} The pane below the active pane
274 {left-of} The pane to the left of the active pane
275 {right-of} The pane to the right of the active pane
276 The tokens ‘+’ and ‘-’ may be followed by an offset, for example:
278 select-window -t:+2
280 In addition, target-session, target-window or target-pane may consist
282 entirely of the token ‘{mouse}’ (alternative form ‘=’) to specify the
283 most recent mouse event (see the MOUSE SUPPORT section) or ‘{marked}’
284 (alternative form ‘~’) to specify the marked pane (see select-pane -m).
285 Sessions, window and panes are each numbered with a unique ID; session
287 IDs are prefixed with a ‘$’, windows with a ‘@’, and panes with a ‘%’.
288 These are unique and are unchanged for the life of the session, window or
289 pane in the tmux server. The pane ID is passed to the child process of
290 the pane in the TMUX_PANE environment variable. IDs may be displayed
291 using the ‘session_id’, ‘window_id’, or ‘pane_id’ formats (see the
292 FORMATS section) and the display-message, list-sessions, list-windows or
293 list-panes commands.
294 shell-command arguments are sh(1) commands. This may be a single argu‐
296 ment passed to the shell, for example:
297 new-window 'vi /etc/passwd'
299 Will run:
301 /bin/sh -c 'vi /etc/passwd'
303 Additionally, the new-window, new-session, split-window, respawn-window
305 and respawn-pane commands allow shell-command to be given as multiple
306 arguments and executed directly (without ‘sh -c’). This can avoid issues
307 with shell quoting. For example:
308 $ tmux new-window vi /etc/passwd
310 Will run vi(1) directly without invoking the shell.
312 command [arguments] refers to a tmux command, passed with the command and
314 arguments separately, for example:
315 bind-key F1 set-window-option force-width 81
317 Or if using sh(1):
319 $ tmux bind-key F1 set-window-option force-width 81
321 Multiple commands may be specified together as part of a command
323 sequence. Each command should be separated by spaces and a semicolon;
324 commands are executed sequentially from left to right and lines ending
325 with a backslash continue on to the next line, except when escaped by
326 another backslash. A literal semicolon may be included by escaping it
327 with a backslash (for example, when specifying a command sequence to
328 bind-key).
329 Example tmux commands include:
331 refresh-client -t/dev/ttyp2
333 rename-session -tfirst newname
335 set-window-option -t:0 monitor-activity on
337 new-window ; split-window -d
339 bind-key R source-file ~/.tmux.conf \; \
341 display-message "source-file done"
342 Or from sh(1):
344 $ tmux kill-window -t :1
346 $ tmux new-window \; split-window -d
348 $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach
350
352 The tmux server manages clients, sessions, windows and panes. Clients
353 are attached to sessions to interact with them, either when they are cre‐
354 ated with the new-session command, or later with the attach-session com‐
355 mand. Each session has one or more windows linked into it. Windows may
356 be linked to multiple sessions and are made up of one or more panes, each
357 of which contains a pseudo terminal. Commands for creating, linking and
358 otherwise manipulating windows are covered in the WINDOWS AND PANES sec‐
359 tion.
360 The following commands are available to manage clients and sessions:
362 attach-session [-dEr] [-c working-directory] [-t target-session]
364 (alias: attach)
365 If run from outside tmux, create a new client in the current ter‐
366 minal and attach it to target-session. If used from inside,
367 switch the current client. If -d is specified, any other clients
368 attached to the session are detached. -r signifies the client is
369 read-only (only keys bound to the detach-client or switch-client
370 commands have any effect)
371 If no server is started, attach-session will attempt to start it;
373 this will fail unless sessions are created in the configuration
374 file.
375 The target-session rules for attach-session are slightly
377 adjusted: if tmux needs to select the most recently used session,
378 it will prefer the most recently used unattached session.
379 -c will set the session working directory (used for new windows)
381 to working-directory.
382 If -E is used, the update-environment option will not be applied.
384 detach-client [-aP] [-E shell-command] [-s target-session] [-t
386 target-client]
387 (alias: detach)
388 Detach the current client if bound to a key, the client specified
389 with -t, or all clients currently attached to the session speci‐
390 fied by -s. The -a option kills all but the client given with
391 -t. If -P is given, send SIGHUP to the parent process of the
392 client, typically causing it to exit. With -E, run shell-command
393 to replace the client.
394 has-session [-t target-session]
396 (alias: has)
397 Report an error and exit with 1 if the specified session does not
398 exist. If it does exist, exit with 0.
399 kill-server
401 Kill the tmux server and clients and destroy all sessions.
402 kill-session [-aC] [-t target-session]
404 Destroy the given session, closing any windows linked to it and
405 no other sessions, and detaching all clients attached to it. If
406 -a is given, all sessions but the specified one is killed. The
407 -C flag clears alerts (bell, activity, or silence) in all windows
408 linked to the session.
409 list-clients [-F format] [-t target-session]
411 (alias: lsc)
412 List all clients attached to the server. For the meaning of the
413 -F flag, see the FORMATS section. If target-session is speci‐
414 fied, list only clients connected to that session.
415 list-commands [-F format]
417 (alias: lscm)
418 List the syntax of all commands supported by tmux.
419 list-sessions [-F format]
421 (alias: ls)
422 List all sessions managed by the server. For the meaning of the
423 -F flag, see the FORMATS section.
424 lock-client [-t target-client]
426 (alias: lockc)
427 Lock target-client, see the lock-server command.
428 lock-session [-t target-session]
430 (alias: locks)
431 Lock all clients attached to target-session.
432 new-session [-AdDEP] [-c start-directory] [-F format] [-n window-name]
434 [-s session-name] [-t group-name] [-x width] [-y height]
435 [shell-command]
436 (alias: new)
437 Create a new session with name session-name.
438 The new session is attached to the current terminal unless -d is
440 given. window-name and shell-command are the name of and shell
441 command to execute in the initial window. With -d, the initial
442 size is 80 x 24; -x and -y can be used to specify a different
443 size.
444 If run from a terminal, any termios(4) special characters are
446 saved and used for new windows in the new session.
447 The -A flag makes new-session behave like attach-session if
449 session-name already exists; in this case, -D behaves like -d to
450 attach-session.
451 If -t is given, it specifies a session group. Sessions in the
453 same group share the same set of windows - new windows are linked
454 to all sessions in the group and any windows closed removed from
455 all sessions. The current and previous window and any session
456 options remain independent and any session in a group may be
457 killed without affecting the others. The group-name argument may
458 be:
459 1. the name of an existing group, in which case the new ses‐
461 sion is added to that group;
462 2. the name of an existing session - the new session is
464 added to the same group as that session, creating a new
465 group if necessary;
466 3. the name for a new group containing only the new session.
468 -n and shell-command are invalid if -t is used.
470 The -P option prints information about the new session after it
472 has been created. By default, it uses the format
473 ‘#{session_name}:’ but a different format may be specified with
474 -F.
475 If -E is used, the update-environment option will not be applied.
477 refresh-client [-C width,height] [-S] [-t target-client]
479 (alias: refresh)
480 Refresh the current client if bound to a key, or a single client
481 if one is given with -t. If -S is specified, only update the
482 client's status line.
483 -C sets the width and height of a control client.
485 rename-session [-t target-session] new-name
487 (alias: rename)
488 Rename the session to new-name.
489 show-messages [-JT] [-t target-client]
491 (alias: showmsgs)
492 Show client messages or server information. Any messages dis‐
493 played on the status line are saved in a per-client message log,
494 up to a maximum of the limit set by the message-limit server
495 option. With -t, display the log for target-client. -J and -T
496 show debugging information about jobs and terminals.
497 source-file [-q] path
499 (alias: source)
500 Execute commands from path (which may be a glob(3) pattern). If
501 -q is given, no error will be returned if path does not exist.
502 Within a configuration file, commands may be made conditional by
504 surrounding them with %if and %endif lines. Additional %elif and
505 %else lines may also be used. The argument to %if and %elif is
506 expanded as a format and if it evaluates to false (zero or
507 empty), subsequent lines are ignored until the next %elif, %else
508 or %endif. For example:
509 %if #{==:#{host},myhost}
511 set -g status-style bg=red
512 %elif #{==:#{host},myotherhost}
513 set -g status-style bg=green
514 %else
515 set -g status-style bg=blue
516 %endif
517 Will change the status line to red if running on ‘myhost’, green
519 if running on ‘myotherhost’, or blue if running on another host.
520 start-server
522 (alias: start)
523 Start the tmux server, if not already running, without creating
524 any sessions.
525 suspend-client [-t target-client]
527 (alias: suspendc)
528 Suspend a client by sending SIGTSTP (tty stop).
529 switch-client [-Elnpr] [-c target-client] [-t target-session] [-T
531 key-table]
532 (alias: switchc)
533 Switch the current session for client target-client to
534 target-session. If -l, -n or -p is used, the client is moved to
535 the last, next or previous session respectively. -r toggles
536 whether a client is read-only (see the attach-session command).
537 If -E is used, update-environment option will not be applied.
539 -T sets the client's key table; the next key from the client will
541 be interpreted from key-table. This may be used to configure
542 multiple prefix keys, or to bind commands to sequences of keys.
543 For example, to make typing ‘abc’ run the list-keys command:
544 bind-key -Ttable2 c list-keys
546 bind-key -Ttable1 b switch-client -Ttable2
547 bind-key -Troot a switch-client -Ttable1
548
550 A tmux window may be in one of two modes. The default permits direct
551 access to the terminal attached to the window. The other is copy mode,
552 which permits a section of a window or its history to be copied to a
553 paste buffer for later insertion into another window. This mode is
554 entered with the copy-mode command, bound to ‘[’ by default. It is also
555 entered when a command that produces output, such as list-keys, is exe‐
556 cuted from a key binding.
557 Commands are sent to copy mode using the -X flag to the send-keys com‐
559 mand. When a key is pressed, copy mode automatically uses one of two key
560 tables, depending on the mode-keys option: copy-mode for emacs, or
561 copy-mode-vi for vi. Key tables may be viewed with the list-keys com‐
562 mand.
563 The following commands are supported in copy mode:
565 Command vi emacs
567 append-selection
568 append-selection-and-cancel A
569 back-to-indentation ^ M-m
570 begin-selection Space C-Space
571 bottom-line L
572 cancel q Escape
573 clear-selection Escape C-g
574 copy-end-of-line D C-k
575 copy-line
576 copy-pipe <command>
577 copy-pipe-and-cancel <command>
578 copy-selection
579 copy-selection-and-cancel Enter M-w
580 cursor-down j Down
581 cursor-left h Left
582 cursor-right l Right
583 cursor-up k Up
584 end-of-line $ C-e
585 goto-line <line> : g
586 halfpage-down C-d M-Down
587 halfpage-down-and-cancel
588 halfpage-up C-u M-Up
589 history-bottom G M->
590 history-top g M-<
591 jump-again ; ;
592 jump-backward <to> F F
593 jump-forward <to> f f
594 jump-reverse , ,
595 jump-to-backward <to> T
596 jump-to-forward <to> t
597 middle-line M M-r
598 next-paragraph } M-}
599 next-space W
600 next-space-end E
601 next-word w
602 next-word-end e M-f
603 other-end o
604 page-down C-f PageDown
605 page-down-and-cancel
606 page-up C-b PageUp
607 previous-paragraph { M-{
608 previous-space B
609 previous-word b M-b
610 rectangle-toggle v R
611 scroll-down C-e C-Down
612 scroll-down-and-cancel
613 scroll-up C-y C-Up
614 search-again n n
615 search-backward <for> ?
616 search-forward <for> /
617 search-backward-incremental <for> C-r
618 search-forward-incremental <for> C-s
619 search-reverse N N
620 select-line V
621 start-of-line 0 C-a
622 stop-selection
623 top-line H M-R
624 The ‘-and-cancel’ variants of some commands exit copy mode after they
626 have completed (for copy commands) or when the cursor reaches the bottom
627 (for scrolling commands).
628 The next and previous word keys use space and the ‘-’, ‘_’ and ‘@’ char‐
630 acters as word delimiters by default, but this can be adjusted by setting
631 the word-separators session option. Next word moves to the start of the
632 next word, next word end to the end of the next word and previous word to
633 the start of the previous word. The three next and previous space keys
634 work similarly but use a space alone as the word separator.
635 The jump commands enable quick movement within a line. For instance,
637 typing ‘f’ followed by ‘/’ will move the cursor to the next ‘/’ character
638 on the current line. A ‘;’ will then jump to the next occurrence.
639 Commands in copy mode may be prefaced by an optional repeat count. With
641 vi key bindings, a prefix is entered using the number keys; with emacs,
642 the Alt (meta) key and a number begins prefix entry.
643 The synopsis for the copy-mode command is:
645 copy-mode [-Meu] [-t target-pane]
647 Enter copy mode. The -u option scrolls one page up. -M begins a
648 mouse drag (only valid if bound to a mouse key binding, see MOUSE
649 SUPPORT). -e specifies that scrolling to the bottom of the his‐
650 tory (to the visible screen) should exit copy mode. While in
651 copy mode, pressing a key other than those used for scrolling
652 will disable this behaviour. This is intended to allow fast
653 scrolling through a pane's history, for example with:
654 bind PageUp copy-mode -eu
656 Each window displayed by tmux may be split into one or more panes; each
658 pane takes up a certain area of the display and is a separate terminal.
659 A window may be split into panes using the split-window command. Windows
660 may be split horizontally (with the -h flag) or vertically. Panes may be
661 resized with the resize-pane command (bound to ‘C-Up’, ‘C-Down’ ‘C-Left’
662 and ‘C-Right’ by default), the current pane may be changed with the
663 select-pane command and the rotate-window and swap-pane commands may be
664 used to swap panes without changing their position. Panes are numbered
665 beginning from zero in the order they are created.
666 A number of preset layouts are available. These may be selected with the
668 select-layout command or cycled with next-layout (bound to ‘Space’ by
669 default); once a layout is chosen, panes within it may be moved and
670 resized as normal.
671 The following layouts are supported:
673 even-horizontal
675 Panes are spread out evenly from left to right across the window.
676 even-vertical
678 Panes are spread evenly from top to bottom.
679 main-horizontal
681 A large (main) pane is shown at the top of the window and the
682 remaining panes are spread from left to right in the leftover
683 space at the bottom. Use the main-pane-height window option to
684 specify the height of the top pane.
685 main-vertical
687 Similar to main-horizontal but the large pane is placed on the
688 left and the others spread from top to bottom along the right.
689 See the main-pane-width window option.
690 tiled Panes are spread out as evenly as possible over the window in
692 both rows and columns.
693 In addition, select-layout may be used to apply a previously used layout
695 - the list-windows command displays the layout of each window in a form
696 suitable for use with select-layout. For example:
697 $ tmux list-windows
699 0: ksh [159x48]
700 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
701 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
702 tmux automatically adjusts the size of the layout for the current window
704 size. Note that a layout cannot be applied to a window with more panes
705 than that from which the layout was originally defined.
706 Commands related to windows and panes are as follows:
708 break-pane [-dP] [-F format] [-n window-name] [-s src-pane] [-t
710 dst-window]
711 (alias: breakp)
712 Break src-pane off from its containing window to make it the only
713 pane in dst-window. If -d is given, the new window does not
714 become the current window. The -P option prints information
715 about the new window after it has been created. By default, it
716 uses the format ‘#{session_name}:#{window_index}’ but a different
717 format may be specified with -F.
718 capture-pane [-aepPqCJ] [-b buffer-name] [-E end-line] [-S start-line]
720 [-t target-pane]
721 (alias: capturep)
722 Capture the contents of a pane. If -p is given, the output goes
723 to stdout, otherwise to the buffer specified with -b or a new
724 buffer if omitted. If -a is given, the alternate screen is used,
725 and the history is not accessible. If no alternate screen
726 exists, an error will be returned unless -q is given. If -e is
727 given, the output includes escape sequences for text and back‐
728 ground attributes. -C also escapes non-printable characters as
729 octal \xxx. -J joins wrapped lines and preserves trailing spaces
730 at each line's end. -P captures only any output that the pane
731 has received that is the beginning of an as-yet incomplete escape
732 sequence.
733 -S and -E specify the starting and ending line numbers, zero is
735 the first line of the visible pane and negative numbers are lines
736 in the history. ‘-’ to -S is the start of the history and to -E
737 the end of the visible pane. The default is to capture only the
738 visible contents of the pane.
739 choose-client [-NZ] [-F format] [-f filter] [-O sort-order] [-t
741 target-pane] [template]
742 Put a pane into client mode, allowing a client to be selected
743 interactively from a list. -Z zooms the pane. The following
744 keys may be used in client mode:
745 Key Function
747 Enter Choose selected client
748 Up Select previous client
749 Down Select next client
750 C-s Search by name
751 n Repeat last search
752 t Toggle if client is tagged
753 T Tag no clients
754 C-t Tag all clients
755 d Detach selected client
756 D Detach tagged clients
757 x Detach and HUP selected client
758 X Detach and HUP tagged clients
759 z Suspend selected client
760 Z Suspend tagged clients
761 f Enter a format to filter items
762 O Change sort order
763 v Toggle preview
764 q Exit mode
765 After a client is chosen, ‘%%’ is replaced by the client name in
767 template and the result executed as a command. If template is
768 not given, "detach-client -t '%%'" is used.
769 -O specifies the initial sort order: one of ‘name’, ‘size’,
771 ‘creation’, or ‘activity’. -f specifies an initial filter: the
772 filter is a format - if it evaluates to zero, the item in the
773 list is not shown, otherwise it is shown. If a filter would lead
774 to an empty list, it is ignored. -F specifies the format for
775 each item in the list. -N starts without the preview. This com‐
776 mand works only if at least one client is attached.
777 choose-tree [-GNswZ] [-F format] [-f filter] [-O sort-order] [-t
779 target-pane] [template]
780 Put a pane into tree mode, where a session, window or pane may be
781 chosen interactively from a list. -s starts with sessions col‐
782 lapsed and -w with windows collapsed. -Z zooms the pane. The
783 following keys may be used in tree mode:
784 Key Function
786 Enter Choose selected item
787 Up Select previous item
788 Down Select next item
789 < Scroll list of previews left
790 > Scroll list of previews right
791 C-s Search by name
792 n Repeat last search
793 t Toggle if item is tagged
794 T Tag no items
795 C-t Tag all items
796 : Run a command for each tagged item
797 f Enter a format to filter items
798 O Change sort order
799 v Toggle preview
800 q Exit mode
801 After a session, window or pane is chosen, ‘%%’ is replaced by
803 the target in template and the result executed as a command. If
804 template is not given, "switch-client -t '%%'" is used.
805 -O specifies the initial sort order: one of ‘index’, ‘name’, or
807 ‘time’. -f specifies an initial filter: the filter is a format -
808 if it evaluates to zero, the item in the list is not shown, oth‐
809 erwise it is shown. If a filter would lead to an empty list, it
810 is ignored. -F specifies the format for each item in the tree.
811 -N starts without the preview. -G includes all sessions in any
812 session groups in the tree rather than only the first. This com‐
813 mand works only if at least one client is attached.
814 display-panes [-d duration] [-t target-client] [template]
816 (alias: displayp)
817 Display a visible indicator of each pane shown by target-client.
818 See the display-panes-colour and display-panes-active-colour ses‐
819 sion options. The indicator is closed when a key is pressed or
820 duration milliseconds have passed. If -d is not given,
821 display-panes-time is used. A duration of zero means the indica‐
822 tor stays until a key is pressed. While the indicator is on
823 screen, a pane may be chosen with the ‘0’ to ‘9’ keys, which will
824 cause template to be executed as a command with ‘%%’ substituted
825 by the pane ID. The default template is "select-pane -t '%%'".
826 find-window [-CNT] [-t target-pane] match-string
828 (alias: findw)
829 Search for the fnmatch(3) pattern match-string in window names,
830 titles, and visible content (but not history). The flags control
831 matching behavior: -C matches only visible window contents, -N
832 matches only the window name and -T matches only the window
833 title. The default is -CNT.
834 This command works only if at least one client is attached.
836 join-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane]
838 (alias: joinp)
839 Like split-window, but instead of splitting dst-pane and creating
840 a new pane, split it and move src-pane into the space. This can
841 be used to reverse break-pane. The -b option causes src-pane to
842 be joined to left of or above dst-pane.
843 If -s is omitted and a marked pane is present (see select-pane
845 -m), the marked pane is used rather than the current pane.
846 kill-pane [-a] [-t target-pane]
848 (alias: killp)
849 Destroy the given pane. If no panes remain in the containing
850 window, it is also destroyed. The -a option kills all but the
851 pane given with -t.
852 kill-window [-a] [-t target-window]
854 (alias: killw)
855 Kill the current window or the window at target-window, removing
856 it from any sessions to which it is linked. The -a option kills
857 all but the window given with -t.
858 last-pane [-de] [-t target-window]
860 (alias: lastp)
861 Select the last (previously selected) pane. -e enables or -d
862 disables input to the pane.
863 last-window [-t target-session]
865 (alias: last)
866 Select the last (previously selected) window. If no
867 target-session is specified, select the last window of the cur‐
868 rent session.
869 link-window [-adk] [-s src-window] [-t dst-window]
871 (alias: linkw)
872 Link the window at src-window to the specified dst-window. If
873 dst-window is specified and no such window exists, the src-window
874 is linked there. With -a, the window is moved to the next index
875 up (following windows are moved if necessary). If -k is given
876 and dst-window exists, it is killed, otherwise an error is gener‐
877 ated. If -d is given, the newly linked window is not selected.
878 list-panes [-as] [-F format] [-t target]
880 (alias: lsp)
881 If -a is given, target is ignored and all panes on the server are
882 listed. If -s is given, target is a session (or the current ses‐
883 sion). If neither is given, target is a window (or the current
884 window). For the meaning of the -F flag, see the FORMATS sec‐
885 tion.
886 list-windows [-a] [-F format] [-t target-session]
888 (alias: lsw)
889 If -a is given, list all windows on the server. Otherwise, list
890 windows in the current session or in target-session. For the
891 meaning of the -F flag, see the FORMATS section.
892 move-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane]
894 (alias: movep)
895 Like join-pane, but src-pane and dst-pane may belong to the same
896 window.
897 move-window [-ardk] [-s src-window] [-t dst-window]
899 (alias: movew)
900 This is similar to link-window, except the window at src-window
901 is moved to dst-window. With -r, all windows in the session are
902 renumbered in sequential order, respecting the base-index option.
903 new-window [-adkP] [-c start-directory] [-F format] [-n window-name] [-t
905 target-window] [shell-command]
906 (alias: neww)
907 Create a new window. With -a, the new window is inserted at the
908 next index up from the specified target-window, moving windows up
909 if necessary, otherwise target-window is the new window location.
910 If -d is given, the session does not make the new window the cur‐
912 rent window. target-window represents the window to be created;
913 if the target already exists an error is shown, unless the -k
914 flag is used, in which case it is destroyed. shell-command is
915 the command to execute. If shell-command is not specified, the
916 value of the default-command option is used. -c specifies the
917 working directory in which the new window is created.
918 When the shell command completes, the window closes. See the
920 remain-on-exit option to change this behaviour.
921 The TERM environment variable must be set to ‘screen’ or ‘tmux’
923 for all programs running inside tmux. New windows will automati‐
924 cally have ‘TERM=screen’ added to their environment, but care
925 must be taken not to reset this in shell start-up files.
926 The -P option prints information about the new window after it
928 has been created. By default, it uses the format
929 ‘#{session_name}:#{window_index}’ but a different format may be
930 specified with -F.
931 next-layout [-t target-window]
933 (alias: nextl)
934 Move a window to the next layout and rearrange the panes to fit.
935 next-window [-a] [-t target-session]
937 (alias: next)
938 Move to the next window in the session. If -a is used, move to
939 the next window with an alert.
940 pipe-pane [-IOo] [-t target-pane] [shell-command]
942 (alias: pipep)
943 Pipe output sent by the program in target-pane to a shell command
944 or vice versa. A pane may only be connected to one command at a
945 time, any existing pipe is closed before shell-command is exe‐
946 cuted. The shell-command string may contain the special charac‐
947 ter sequences supported by the status-left option. If no
948 shell-command is given, the current pipe (if any) is closed.
949 -I and -O specify which of the shell-command output streams are
951 connected to the pane: with -I stdout is connected (so anything
952 shell-command prints is written to the pane as if it were typed);
953 with -O stdin is connected (so any output in the pane is piped to
954 shell-command). Both may be used together and if neither are
955 specified, -O is used.
956 The -o option only opens a new pipe if no previous pipe exists,
958 allowing a pipe to be toggled with a single key, for example:
959 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
961 previous-layout [-t target-window]
963 (alias: prevl)
964 Move to the previous layout in the session.
965 previous-window [-a] [-t target-session]
967 (alias: prev)
968 Move to the previous window in the session. With -a, move to the
969 previous window with an alert.
970 rename-window [-t target-window] new-name
972 (alias: renamew)
973 Rename the current window, or the window at target-window if
974 specified, to new-name.
975 resize-pane [-DLMRUZ] [-t target-pane] [-x width] [-y height]
977 [adjustment]
978 (alias: resizep)
979 Resize a pane, up, down, left or right by adjustment with -U, -D,
980 -L or -R, or to an absolute size with -x or -y. The adjustment
981 is given in lines or cells (the default is 1).
982 With -Z, the active pane is toggled between zoomed (occupying the
984 whole of the window) and unzoomed (its normal position in the
985 layout).
986 -M begins mouse resizing (only valid if bound to a mouse key
988 binding, see MOUSE SUPPORT).
989 respawn-pane [-c start-directory] [-k] [-t target-pane] [shell-command]
991 (alias: respawnp)
992 Reactivate a pane in which the command has exited (see the
993 remain-on-exit window option). If shell-command is not given,
994 the command used when the pane was created is executed. The pane
995 must be already inactive, unless -k is given, in which case any
996 existing command is killed. -c specifies a new working directory
997 for the pane.
998 respawn-window [-c start-directory] [-k] [-t target-window]
1000 [shell-command]
1001 (alias: respawnw)
1002 Reactivate a window in which the command has exited (see the
1003 remain-on-exit window option). If shell-command is not given,
1004 the command used when the window was created is executed. The
1005 window must be already inactive, unless -k is given, in which
1006 case any existing command is killed. -c specifies a new working
1007 directory for the window.
1008 rotate-window [-DU] [-t target-window]
1010 (alias: rotatew)
1011 Rotate the positions of the panes within a window, either upward
1012 (numerically lower) with -U or downward (numerically higher).
1013 select-layout [-Enop] [-t target-pane] [layout-name]
1015 (alias: selectl)
1016 Choose a specific layout for a window. If layout-name is not
1017 given, the last preset layout used (if any) is reapplied. -n and
1018 -p are equivalent to the next-layout and previous-layout com‐
1019 mands. -o applies the last set layout if possible (undoes the
1020 most recent layout change). -E spreads the current pane and any
1021 panes next to it out evenly.
1022 select-pane [-DdegLlMmRU] [-P style] [-T title] [-t target-pane]
1024 (alias: selectp)
1025 Make pane target-pane the active pane in window target-window, or
1026 set its style (with -P). If one of -D, -L, -R, or -U is used,
1027 respectively the pane below, to the left, to the right, or above
1028 the target pane is used. -l is the same as using the last-pane
1029 command. -e enables or -d disables input to the pane.
1030 -m and -M are used to set and clear the marked pane. There is
1032 one marked pane at a time, setting a new marked pane clears the
1033 last. The marked pane is the default target for -s to join-pane,
1034 swap-pane and swap-window.
1035 Each pane has a style: by default the window-style and
1037 window-active-style options are used, select-pane -P sets the
1038 style for a single pane. For example, to set the pane 1 back‐
1039 ground to red:
1040 select-pane -t:.1 -P 'bg=red'
1042 -g shows the current pane style.
1044 -T sets the pane title.
1046 select-window [-lnpT] [-t target-window]
1048 (alias: selectw)
1049 Select the window at target-window. -l, -n and -p are equivalent
1050 to the last-window, next-window and previous-window commands. If
1051 -T is given and the selected window is already the current win‐
1052 dow, the command behaves like last-window.
1053 split-window [-bdfhvP] [-c start-directory] [-l size | -p percentage] [-t
1055 target-pane] [shell-command] [-F format]
1056 (alias: splitw)
1057 Create a new pane by splitting target-pane: -h does a horizontal
1058 split and -v a vertical split; if neither is specified, -v is
1059 assumed. The -l and -p options specify the size of the new pane
1060 in lines (for vertical split) or in cells (for horizontal split),
1061 or as a percentage, respectively. The -b option causes the new
1062 pane to be created to the left of or above target-pane. The -f
1063 option creates a new pane spanning the full window height (with
1064 -h) or full window width (with -v), instead of splitting the
1065 active pane. All other options have the same meaning as for the
1066 new-window command.
1067 swap-pane [-dDU] [-s src-pane] [-t dst-pane]
1069 (alias: swapp)
1070 Swap two panes. If -U is used and no source pane is specified
1071 with -s, dst-pane is swapped with the previous pane (before it
1072 numerically); -D swaps with the next pane (after it numerically).
1073 -d instructs tmux not to change the active pane.
1074 If -s is omitted and a marked pane is present (see select-pane
1076 -m), the marked pane is used rather than the current pane.
1077 swap-window [-d] [-s src-window] [-t dst-window]
1079 (alias: swapw)
1080 This is similar to link-window, except the source and destination
1081 windows are swapped. It is an error if no window exists at
1082 src-window.
1083 Like swap-pane, if -s is omitted and a marked pane is present
1085 (see select-pane -m), the window containing the marked pane is
1086 used rather than the current window.
1087 unlink-window [-k] [-t target-window]
1089 (alias: unlinkw)
1090 Unlink target-window. Unless -k is given, a window may be
1091 unlinked only if it is linked to multiple sessions - windows may
1092 not be linked to no sessions; if -k is specified and the window
1093 is linked to only one session, it is unlinked and destroyed.
1094
1096 tmux allows a command to be bound to most keys, with or without a prefix
1097 key. When specifying keys, most represent themselves (for example ‘A’ to
1098 ‘Z’). Ctrl keys may be prefixed with ‘C-’ or ‘^’, and Alt (meta) with
1099 ‘M-’. In addition, the following special key names are accepted: Up,
1100 Down, Left, Right, BSpace, BTab, DC (Delete), End, Enter, Escape, F1 to
1101 F12, Home, IC (Insert), NPage/PageDown/PgDn, PPage/PageUp/PgUp, Space,
1102 and Tab. Note that to bind the ‘"’ or ‘'’ keys, quotation marks are nec‐
1103 essary, for example:
1104 bind-key '"' split-window
1106 bind-key "'" new-window
1107 Commands related to key bindings are as follows:
1109 bind-key [-nr] [-T key-table] key command [arguments]
1111 (alias: bind)
1112 Bind key key to command. Keys are bound in a key table. By
1113 default (without -T), the key is bound in the prefix key table.
1114 This table is used for keys pressed after the prefix key (for
1115 example, by default ‘c’ is bound to new-window in the prefix ta‐
1116 ble, so ‘C-b c’ creates a new window). The root table is used
1117 for keys pressed without the prefix key: binding ‘c’ to
1118 new-window in the root table (not recommended) means a plain ‘c’
1119 will create a new window. -n is an alias for -T root. Keys may
1120 also be bound in custom key tables and the switch-client -T com‐
1121 mand used to switch to them from a key binding. The -r flag
1122 indicates this key may repeat, see the repeat-time option.
1123 To view the default bindings and possible commands, see the
1125 list-keys command.
1126 list-keys [-T key-table]
1128 (alias: lsk)
1129 List all key bindings. Without -T all key tables are printed.
1130 With -T only key-table.
1131 send-keys [-lMRX] [-N repeat-count] [-t target-pane] key ...
1133 (alias: send)
1134 Send a key or keys to a window. Each argument key is the name of
1135 the key (such as ‘C-a’ or ‘NPage’) to send; if the string is not
1136 recognised as a key, it is sent as a series of characters. The
1137 -l flag disables key name lookup and sends the keys literally.
1138 All arguments are sent sequentially from first to last. The -R
1139 flag causes the terminal state to be reset.
1140 -M passes through a mouse event (only valid if bound to a mouse
1142 key binding, see MOUSE SUPPORT).
1143 -X is used to send a command into copy mode - see the WINDOWS AND
1145 PANES section. -N specifies a repeat count.
1146 send-prefix [-2] [-t target-pane]
1148 Send the prefix key, or with -2 the secondary prefix key, to a
1149 window as if it was pressed.
1150 unbind-key [-an] [-T key-table] key
1152 (alias: unbind)
1153 Unbind the command bound to key. -n and -T are the same as for
1154 bind-key. If -a is present, all key bindings are removed.
1155
1157 The appearance and behaviour of tmux may be modified by changing the
1158 value of various options. There are three types of option: server
1159 options, session options and window options.
1160 The tmux server has a set of global options which do not apply to any
1162 particular window or session. These are altered with the set-option -s
1163 command, or displayed with the show-options -s command.
1164 In addition, each individual session may have a set of session options,
1166 and there is a separate set of global session options. Sessions which do
1167 not have a particular option configured inherit the value from the global
1168 session options. Session options are set or unset with the set-option
1169 command and may be listed with the show-options command. The available
1170 server and session options are listed under the set-option command.
1171 Similarly, a set of window options is attached to each window, and there
1173 is a set of global window options from which any unset options are inher‐
1174 ited. Window options are altered with the set-window-option command and
1175 can be listed with the show-window-options command. All window options
1176 are documented with the set-window-option command.
1177 tmux also supports user options which are prefixed with a ‘@’. User
1179 options may have any name, so long as they are prefixed with ‘@’, and be
1180 set to any string. For example:
1181 $ tmux setw -q @foo "abc123"
1183 $ tmux showw -v @foo
1184 abc123
1185 Commands which set options are as follows:
1187 set-option [-aFgoqsuw] [-t target-session | target-window] option value
1189 (alias: set)
1190 Set a window option with -w (equivalent to the set-window-option
1191 command), a server option with -s, otherwise a session option.
1192 If -g is given, the global session or window option is set. -F
1193 expands formats in the option value. The -u flag unsets an
1194 option, so a session inherits the option from the global options
1195 (or with -g, restores a global option to the default).
1196 The -o flag prevents setting an option that is already set and
1198 the -q flag suppresses errors about unknown or ambiguous options.
1199 With -a, and if the option expects a string or a style, value is
1201 appended to the existing setting. For example:
1202 set -g status-left "foo"
1204 set -ag status-left "bar"
1205 Will result in ‘foobar’. And:
1207 set -g status-style "bg=red"
1209 set -ag status-style "fg=blue"
1210 Will result in a red background and blue foreground. Without -a,
1212 the result would be the default background and a blue foreground.
1213 Available window options are listed under set-window-option.
1215 value depends on the option and may be a number, a string, or a
1217 flag (on, off, or omitted to toggle).
1218 Available server options are:
1220 buffer-limit number
1222 Set the number of buffers; as new buffers are added to
1223 the top of the stack, old ones are removed from the bot‐
1224 tom if necessary to maintain this maximum length.
1225 command-alias[] name=value
1227 This is an array of custom aliases for commands. If an
1228 unknown command matches name, it is replaced with value.
1229 For example, after:
1230 set -s command-alias[100] zoom='resize-pane -Z'
1232 Using:
1234 zoom -t:.1
1236 Is equivalent to:
1238 resize-pane -Z -t:.1
1240 Note that aliases are expanded when a command is parsed
1242 rather than when it is executed, so binding an alias with
1243 bind-key will bind the expanded form.
1244 default-terminal terminal
1246 Set the default terminal for new windows created in this
1247 session - the default value of the TERM environment vari‐
1248 able. For tmux to work correctly, this must be set to
1249 ‘screen’, ‘tmux’ or a derivative of them.
1250 escape-time time
1252 Set the time in milliseconds for which tmux waits after
1253 an escape is input to determine if it is part of a func‐
1254 tion or meta key sequences. The default is 500 millisec‐
1255 onds.
1256 exit-empty [on | off]
1258 If enabled (the default), the server will exit when there
1259 are no active sessions.
1260 exit-unattached [on | off]
1262 If enabled, the server will exit when there are no
1263 attached clients.
1264 focus-events [on | off]
1266 When enabled, focus events are requested from the termi‐
1267 nal if supported and passed through to applications run‐
1268 ning in tmux. Attached clients should be detached and
1269 attached again after changing this option.
1270 history-file path
1272 If not empty, a file to which tmux will write command
1273 prompt history on exit and load it from on start.
1274 message-limit number
1276 Set the number of error or information messages to save
1277 in the message log for each client. The default is 100.
1278 set-clipboard [on | external | off]
1280 Attempt to set the terminal clipboard content using the
1281 xterm(1) escape sequence, if there is an Ms entry in the
1282 terminfo(5) description (see the TERMINFO EXTENSIONS sec‐
1283 tion).
1284 If set to on, tmux will both accept the escape sequence
1286 to create a buffer and attempt to set the terminal clip‐
1287 board. If set to external, tmux will attempt to set the
1288 terminal clipboard but ignore attempts by applications to
1289 set tmux buffers. If off, tmux will neither accept the
1290 clipboard escape sequence nor attempt to set the clip‐
1291 board.
1292 Note that this feature needs to be enabled in xterm(1) by
1294 setting the resource:
1295 disallowedWindowOps: 20,21,SetXprop
1297 Or changing this property from the xterm(1) interactive
1299 menu when required.
1300 terminal-overrides[] string
1302 Allow terminal descriptions read using terminfo(5) to be
1303 overridden. Each entry is a colon-separated string made
1304 up of a terminal type pattern (matched using fnmatch(3))
1305 and a set of name=value entries.
1306 For example, to set the ‘clear’ terminfo(5) entry to
1308 ‘\e[H\e[2J’ for all terminal types matching ‘rxvt*’:
1309 rxvt*:clear=\e[H\e[2J
1311 The terminal entry value is passed through strunvis(3)
1313 before interpretation.
1314 Available session options are:
1316 activity-action [any | none | current | other]
1318 Set action on window activity when monitor-activity is
1319 on. any means activity in any window linked to a session
1320 causes a bell or message (depending on visual-activity)
1321 in the current window of that session, none means all
1322 activity is ignored (equivalent to monitor-activity being
1323 off), current means only activity in windows other than
1324 the current window are ignored and other means activity
1325 in the current window is ignored but not those in other
1326 windows.
1327 assume-paste-time milliseconds
1329 If keys are entered faster than one in milliseconds, they
1330 are assumed to have been pasted rather than typed and
1331 tmux key bindings are not processed. The default is one
1332 millisecond and zero disables.
1333 base-index index
1335 Set the base index from which an unused index should be
1336 searched when a new window is created. The default is
1337 zero.
1338 bell-action [any | none | current | other]
1340 Set action on a bell in a window when monitor-bell is on.
1341 The values are the same as those for activity-action.
1342 default-command shell-command
1344 Set the command used for new windows (if not specified
1345 when the window is created) to shell-command, which may
1346 be any sh(1) command. The default is an empty string,
1347 which instructs tmux to create a login shell using the
1348 value of the default-shell option.
1349 default-shell path
1351 Specify the default shell. This is used as the login
1352 shell for new windows when the default-command option is
1353 set to empty, and must be the full path of the exe‐
1354 cutable. When started tmux tries to set a default value
1355 from the first suitable of the SHELL environment vari‐
1356 able, the shell returned by getpwuid(3), or /bin/sh.
1357 This option should be configured when tmux is used as a
1358 login shell.
1359 destroy-unattached [on | off]
1361 If enabled and the session is no longer attached to any
1362 clients, it is destroyed.
1363 detach-on-destroy [on | off]
1365 If on (the default), the client is detached when the ses‐
1366 sion it is attached to is destroyed. If off, the client
1367 is switched to the most recently active of the remaining
1368 sessions.
1369 display-panes-active-colour colour
1371 Set the colour used by the display-panes command to show
1372 the indicator for the active pane.
1373 display-panes-colour colour
1375 Set the colour used by the display-panes command to show
1376 the indicators for inactive panes.
1377 display-panes-time time
1379 Set the time in milliseconds for which the indicators
1380 shown by the display-panes command appear.
1381 display-time time
1383 Set the amount of time for which status line messages and
1384 other on-screen indicators are displayed. If set to 0,
1385 messages and indicators are displayed until a key is
1386 pressed. time is in milliseconds.
1387 history-limit lines
1389 Set the maximum number of lines held in window history.
1390 This setting applies only to new windows - existing win‐
1391 dow histories are not resized and retain the limit at the
1392 point they were created.
1393 key-table key-table
1395 Set the default key table to key-table instead of root.
1396 lock-after-time number
1398 Lock the session (like the lock-session command) after
1399 number seconds of inactivity. The default is not to lock
1400 (set to 0).
1401 lock-command shell-command
1403 Command to run when locking each client. The default is
1404 to run lock(1) with -np.
1405 message-command-style style
1407 Set status line message command style, where style is a
1408 comma-separated list of characteristics to be specified.
1409 These may be ‘bg=colour’ to set the background colour,
1411 ‘fg=colour’ to set the foreground colour, and a list of
1412 attributes as specified below.
1413 The colour is one of: black, red, green, yellow, blue,
1415 magenta, cyan, white, aixterm bright variants (if sup‐
1416 ported: brightred, brightgreen, and so on), colour0 to
1417 colour255 from the 256-colour set, default, or a hexadec‐
1418 imal RGB string such as ‘#ffffff’, which chooses the
1419 closest match from the default 256-colour set.
1420 The attributes is either none or a comma-delimited list
1422 of one or more of: bright (or bold), dim, underscore,
1423 blink, reverse, hidden, italics, or strikethrough to turn
1424 an attribute on, or an attribute prefixed with ‘no’ to
1425 turn one off.
1426 Examples are:
1428 fg=yellow,bold,underscore,blink
1430 bg=black,fg=default,noreverse
1431 With the -a flag to the set-option command the new style
1433 is added otherwise the existing style is replaced.
1434 message-style style
1436 Set status line message style. For how to specify style,
1437 see the message-command-style option.
1438 mouse [on | off]
1440 If on, tmux captures the mouse and allows mouse events to
1441 be bound as key bindings. See the MOUSE SUPPORT section
1442 for details.
1443 prefix key
1445 Set the key accepted as a prefix key. In addition to the
1446 standard keys described under KEY BINDINGS, prefix can be
1447 set to the special key ‘None’ to set no prefix.
1448 prefix2 key
1450 Set a secondary key accepted as a prefix key. Like
1451 prefix, prefix2 can be set to ‘None’.
1452 renumber-windows [on | off]
1454 If on, when a window is closed in a session, automati‐
1455 cally renumber the other windows in numerical order.
1456 This respects the base-index option if it has been set.
1457 If off, do not renumber the windows.
1458 repeat-time time
1460 Allow multiple commands to be entered without pressing
1461 the prefix-key again in the specified time milliseconds
1462 (the default is 500). Whether a key repeats may be set
1463 when it is bound using the -r flag to bind-key. Repeat
1464 is enabled for the default keys bound to the resize-pane
1465 command.
1466 set-titles [on | off]
1468 Attempt to set the client terminal title using the tsl
1469 and fsl terminfo(5) entries if they exist. tmux automat‐
1470 ically sets these to the \e]0;...\007 sequence if the
1471 terminal appears to be xterm(1). This option is off by
1472 default.
1473 set-titles-string string
1475 String used to set the window title if set-titles is on.
1476 Formats are expanded, see the FORMATS section.
1477 silence-action [any | none | current | other]
1479 Set action on window silence when monitor-silence is on.
1480 The values are the same as those for activity-action.
1481 status [on | off]
1483 Show or hide the status line.
1484 status-interval interval
1486 Update the status line every interval seconds. By
1487 default, updates will occur every 15 seconds. A setting
1488 of zero disables redrawing at interval.
1489 status-justify [left | centre | right]
1491 Set the position of the window list component of the sta‐
1492 tus line: left, centre or right justified.
1493 status-keys [vi | emacs]
1495 Use vi or emacs-style key bindings in the status line,
1496 for example at the command prompt. The default is emacs,
1497 unless the VISUAL or EDITOR environment variables are set
1498 and contain the string ‘vi’.
1499 status-left string
1501 Display string (by default the session name) to the left
1502 of the status line. string will be passed through
1503 strftime(3) and formats (see FORMATS) will be expanded.
1504 It may also contain the special character sequence #[] to
1505 change the colour or attributes, for example
1506 ‘#[fg=red,bright]’ to set a bright red foreground. See
1507 the message-command-style option for a description of
1508 colours and attributes.
1509 For details on how the names and titles can be set see
1511 the NAMES AND TITLES section.
1512 Examples are:
1514 #(sysctl vm.loadavg)
1516 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
1517 The default is ‘[#S] ’.
1519 status-left-length length
1521 Set the maximum length of the left component of the sta‐
1522 tus line. The default is 10.
1523 status-left-style style
1525 Set the style of the left part of the status line. For
1526 how to specify style, see the message-command-style
1527 option.
1528 status-position [top | bottom]
1530 Set the position of the status line.
1531 status-right string
1533 Display string to the right of the status line. By
1534 default, the current pane title in double quotes, the
1535 date and the time are shown. As with status-left, string
1536 will be passed to strftime(3) and character pairs are
1537 replaced.
1538 status-right-length length
1540 Set the maximum length of the right component of the sta‐
1541 tus line. The default is 40.
1542 status-right-style style
1544 Set the style of the right part of the status line. For
1545 how to specify style, see the message-command-style
1546 option.
1547 status-style style
1549 Set status line style. For how to specify style, see the
1550 message-command-style option.
1551 update-environment[] variable
1553 Set list of environment variables to be copied into the
1554 session environment when a new session is created or an
1555 existing session is attached. Any variables that do not
1556 exist in the source environment are set to be removed
1557 from the session environment (as if -r was given to the
1558 set-environment command).
1559 user-keys[] key
1561 Set list of user-defined key escape sequences. Each item
1562 is associated with a key named ‘User0’, ‘User1’, and so
1563 on.
1564 For example:
1566 set -s user-keys[0] "\e[5;30012~"
1568 bind User0 resize-pane -L 3
1569 visual-activity [on | off | both]
1571 If on, display a message instead of sending a bell when
1572 activity occurs in a window for which the
1573 monitor-activity window option is enabled. If set to
1574 both, a bell and a message are produced.
1575 visual-bell [on | off | both]
1577 If on, a message is shown on a bell in a window for which
1578 the monitor-bell window option is enabled instead of it
1579 being passed through to the terminal (which normally
1580 makes a sound). If set to both, a bell and a message are
1581 produced. Also see the bell-action option.
1582 visual-silence [on | off | both]
1584 If monitor-silence is enabled, prints a message after the
1585 interval has expired on a given window instead of sending
1586 a bell. If set to both, a bell and a message are pro‐
1587 duced.
1588 word-separators string
1590 Sets the session's conception of what characters are con‐
1591 sidered word separators, for the purposes of the next and
1592 previous word commands in copy mode. The default is
1593 ‘ -_@’.
1594 set-window-option [-aFgoqu] [-t target-window] option value
1596 (alias: setw)
1597 Set a window option. The -a, -F, -g, -o, -q and -u flags work
1598 similarly to the set-option command.
1599 Supported window options are:
1601 aggressive-resize [on | off]
1603 Aggressively resize the chosen window. This means that
1604 tmux will resize the window to the size of the smallest
1605 session for which it is the current window, rather than
1606 the smallest session to which it is attached. The window
1607 may resize when the current window is changed on another
1608 sessions; this option is good for full-screen programs
1609 which support SIGWINCH and poor for interactive programs
1610 such as shells.
1611 allow-rename [on | off]
1613 Allow programs to change the window name using a terminal
1614 escape sequence (\ek...\e\\). The default is off.
1615 alternate-screen [on | off]
1617 This option configures whether programs running inside
1618 tmux may use the terminal alternate screen feature, which
1619 allows the smcup and rmcup terminfo(5) capabilities. The
1620 alternate screen feature preserves the contents of the
1621 window when an interactive application starts and
1622 restores it on exit, so that any output visible before
1623 the application starts reappears unchanged after it
1624 exits. The default is on.
1625 automatic-rename [on | off]
1627 Control automatic window renaming. When this setting is
1628 enabled, tmux will rename the window automatically using
1629 the format specified by automatic-rename-format. This
1630 flag is automatically disabled for an individual window
1631 when a name is specified at creation with new-window or
1632 new-session, or later with rename-window, or with a ter‐
1633 minal escape sequence. It may be switched off globally
1634 with:
1635 set-window-option -g automatic-rename off
1637 automatic-rename-format format
1639 The format (see FORMATS) used when the automatic-rename
1640 option is enabled.
1641 clock-mode-colour colour
1643 Set clock colour.
1644 clock-mode-style [12 | 24]
1646 Set clock hour format.
1647 force-height height
1649 force-width width
1650 Prevent tmux from resizing a window to greater than width
1651 or height. A value of zero restores the default unlim‐
1652 ited setting.
1653 main-pane-height height
1655 main-pane-width width
1656 Set the width or height of the main (left or top) pane in
1657 the main-horizontal or main-vertical layouts.
1658 mode-keys [vi | emacs]
1660 Use vi or emacs-style key bindings in copy mode. The
1661 default is emacs, unless VISUAL or EDITOR contains ‘vi’.
1662 mode-style style
1664 Set window modes style. For how to specify style, see
1665 the message-command-style option.
1666 monitor-activity [on | off]
1668 Monitor for activity in the window. Windows with activ‐
1669 ity are highlighted in the status line.
1670 monitor-bell [on | off]
1672 Monitor for a bell in the window. Windows with a bell
1673 are highlighted in the status line.
1674 monitor-silence [interval]
1676 Monitor for silence (no activity) in the window within
1677 interval seconds. Windows that have been silent for the
1678 interval are highlighted in the status line. An interval
1679 of zero disables the monitoring.
1680 other-pane-height height
1682 Set the height of the other panes (not the main pane) in
1683 the main-horizontal layout. If this option is set to 0
1684 (the default), it will have no effect. If both the
1685 main-pane-height and other-pane-height options are set,
1686 the main pane will grow taller to make the other panes
1687 the specified height, but will never shrink to do so.
1688 other-pane-width width
1690 Like other-pane-height, but set the width of other panes
1691 in the main-vertical layout.
1692 pane-active-border-style style
1694 Set the pane border style for the currently active pane.
1695 For how to specify style, see the message-command-style
1696 option. Attributes are ignored.
1697 pane-base-index index
1699 Like base-index, but set the starting index for pane num‐
1700 bers.
1701 pane-border-format format
1703 Set the text shown in pane border status lines.
1704 pane-border-status [off | top | bottom]
1706 Turn pane border status lines off or set their position.
1707 pane-border-style style
1709 Set the pane border style for panes aside from the active
1710 pane. For how to specify style, see the
1711 message-command-style option. Attributes are ignored.
1712 remain-on-exit [on | off]
1714 A window with this flag set is not destroyed when the
1715 program running in it exits. The window may be reacti‐
1716 vated with the respawn-window command.
1717 synchronize-panes [on | off]
1719 Duplicate input to any pane to all other panes in the
1720 same window (only for panes that are not in any special
1721 mode).
1722 window-active-style style
1724 Set the style for the window's active pane. For how to
1725 specify style, see the message-command-style option.
1726 window-status-activity-style style
1728 Set status line style for windows with an activity alert.
1729 For how to specify style, see the message-command-style
1730 option.
1731 window-status-bell-style style
1733 Set status line style for windows with a bell alert. For
1734 how to specify style, see the message-command-style
1735 option.
1736 window-status-current-format string
1738 Like window-status-format, but is the format used when
1739 the window is the current window.
1740 window-status-current-style style
1742 Set status line style for the currently active window.
1743 For how to specify style, see the message-command-style
1744 option.
1745 window-status-format string
1747 Set the format in which the window is displayed in the
1748 status line window list. See the status-left option for
1749 details of special character sequences available. The
1750 default is ‘#I:#W#F’.
1751 window-status-last-style style
1753 Set status line style for the last active window. For
1754 how to specify style, see the message-command-style
1755 option.
1756 window-status-separator string
1758 Sets the separator drawn between windows in the status
1759 line. The default is a single space character.
1760 window-status-style style
1762 Set status line style for a single window. For how to
1763 specify style, see the message-command-style option.
1764 window-style style
1766 Set the default window style. For how to specify style,
1767 see the message-command-style option.
1768 wrap-search [on | off]
1770 If this option is set, searches will wrap around the end
1771 of the pane contents. The default is on.
1772 xterm-keys [on | off]
1774 If this option is set, tmux will generate xterm(1) -style
1775 function key sequences; these have a number included to
1776 indicate modifiers such as Shift, Alt or Ctrl.
1777 show-options [-gqsvw] [-t target-session | target-window] [option]
1779 (alias: show)
1780 Show the window options (or a single window option if given) with
1781 -w (equivalent to show-window-options), the server options with
1782 -s, otherwise the session options for target session. Global
1783 session or window options are listed if -g is used. -v shows
1784 only the option value, not the name. If -q is set, no error will
1785 be returned if option is unset.
1786 show-window-options [-gv] [-t target-window] [option]
1788 (alias: showw)
1789 List the window options or a single option for target-window, or
1790 the global window options if -g is used. -v shows only the
1791 option value, not the name.
1792
1794 tmux allows commands to run on various triggers, called hooks. Most tmux
1795 commands have an after hook and there are a number of hooks not associ‐
1796 ated with commands.
1797 A command's after hook is run after it completes, except when the command
1799 is run as part of a hook itself. They are named with an ‘after-’ prefix.
1800 For example, the following command adds a hook to select the even-verti‐
1801 cal layout after every split-window:
1802 set-hook after-split-window "selectl even-vertical"
1804 All the notifications listed in the CONTROL MODE section are hooks (with‐
1806 out any arguments), except %exit. The following additional hooks are
1807 available:
1808 alert-activity Run when a window has activity. See
1810 monitor-activity.
1811 alert-bell Run when a window has received a bell. See
1813 monitor-bell.
1814 alert-silence Run when a window has been silent. See
1816 monitor-silence.
1817 client-attached Run when a client is attached.
1819 client-detached Run when a client is detached
1821 client-resized Run when a client is resized.
1823 client-session-changed Run when a client's attached session is changed.
1825 pane-died Run when the program running in a pane exits, but
1827 remain-on-exit is on so the pane has not closed.
1828 pane-exited Run when the program running in a pane exits.
1830 pane-set-clipboard Run when the terminal clipboard is set using the
1832 xterm(1) escape sequence.
1833 session-created Run when a new session created.
1835 session-closed Run when a session closed.
1837 session-renamed Run when a session is renamed.
1839 window-linked Run when a window is linked into a session.
1841 window-renamed Run when a window is renamed.
1843 window-unlinked Run when a window is unlinked from a session.
1845 Hooks are managed with these commands:
1847 set-hook [-gu] [-t target-session] hook-name command
1849 Sets (or with -u unsets) hook hook-name to command. If -g is
1850 given, hook-name is added to the global list of hooks, otherwise
1851 it is added to the session hooks (for target-session with -t).
1852 Like options, session hooks inherit from the global ones.
1853 show-hooks [-g] [-t target-session]
1855 Shows the global list of hooks with -g, otherwise the session
1856 hooks.
1857
1859 If the mouse option is on (the default is off), tmux allows mouse events
1860 to be bound as keys. The name of each key is made up of a mouse event
1861 (such as ‘MouseUp1’) and a location suffix (one of ‘Pane’ for the con‐
1862 tents of a pane, ‘Border’ for a pane border or ‘Status’ for the status
1863 line). The following mouse events are available:
1864 WheelUp WheelDown
1866 MouseDown1 MouseUp1 MouseDrag1 MouseDragEnd1
1867 MouseDown2 MouseUp2 MouseDrag2 MouseDragEnd2
1868 MouseDown3 MouseUp3 MouseDrag3 MouseDragEnd3
1869 DoubleClick1 DoubleClick2 DoubleClick3
1870 TripleClick1 TripleClick2 TripleClick3
1871 Each should be suffixed with a location, for example ‘MouseDown1Status’.
1873 The special token ‘{mouse}’ or ‘=’ may be used as target-window or
1875 target-pane in commands bound to mouse key bindings. It resolves to the
1876 window or pane over which the mouse event took place (for example, the
1877 window in the status line over which button 1 was released for a
1878 ‘MouseUp1Status’ binding, or the pane over which the wheel was scrolled
1879 for a ‘WheelDownPane’ binding).
1880 The send-keys -M flag may be used to forward a mouse event to a pane.
1882 The default key bindings allow the mouse to be used to select and resize
1884 panes, to copy text and to change window using the status line. These
1885 take effect if the mouse option is turned on.
1886
1888 Certain commands accept the -F flag with a format argument. This is a
1889 string which controls the output format of the command. Replacement
1890 variables are enclosed in ‘#{’ and ‘}’, for example ‘#{session_name}’.
1891 The possible variables are listed in the table below, or the name of a
1892 tmux option may be used for an option's value. Some variables have a
1893 shorter alias such as ‘#S’, and ‘##’ is replaced by a single ‘#’.
1894 Conditionals are available by prefixing with ‘?’ and separating two
1896 alternatives with a comma; if the specified variable exists and is not
1897 zero, the first alternative is chosen, otherwise the second is used. For
1898 example ‘#{?session_attached,attached,not attached}’ will include the
1899 string ‘attached’ if the session is attached and the string ‘not
1900 attached’ if it is unattached, or ‘#{?automatic-rename,yes,no}’ will
1901 include ‘yes’ if automatic-rename is enabled, or ‘no’ if not.
1902 Comparisons may be expressed by prefixing two comma-separated alterna‐
1904 tives by ‘==’ or ‘!=’ and a colon. For example ‘#{==:#{host},myhost}’
1905 will be replaced by ‘1’ if running on ‘myhost’, otherwise by ‘0’. An ‘m’
1906 specifies an fnmatch(3) comparison where the first argument is the pat‐
1907 tern and the second the string to compare, for example
1908 ‘#{m:*foo*,#{host}}’. ‘||’ and ‘&&’ evaluate to true if either or both
1909 of two comma-separated alternatives are true, for example
1910 ‘#{||,#{pane_in_mode},#{alternate_on}}’. A ‘C’ performs a search for an
1911 fnmatch(3) pattern in the pane content and evaluates to zero if not
1912 found, or a line number if found.
1913 A limit may be placed on the length of the resultant string by prefixing
1915 it by an ‘=’, a number and a colon. Positive numbers count from the
1916 start of the string and negative from the end, so ‘#{=5:pane_title}’ will
1917 include at most the first 5 characters of the pane title, or
1918 ‘#{=-5:pane_title}’ the last 5 characters. Prefixing a time variable
1919 with ‘t:’ will convert it to a string, so if ‘#{window_activity}’ gives
1920 ‘1445765102’, ‘#{t:window_activity}’ gives ‘Sun Oct 25 09:25:02 2015’.
1921 The ‘b:’ and ‘d:’ prefixes are basename(3) and dirname(3) of the variable
1922 respectively. A prefix of the form ‘s/foo/bar/:’ will substitute ‘foo’
1923 with ‘bar’ throughout.
1924 In addition, the first line of a shell command's output may be inserted
1926 using ‘#()’. For example, ‘#(uptime)’ will insert the system's uptime.
1927 When constructing formats, tmux does not wait for ‘#()’ commands to fin‐
1928 ish; instead, the previous result from running the same command is used,
1929 or a placeholder if the command has not been run before. If the command
1930 hasn't exited, the most recent line of output will be used, but the sta‐
1931 tus line will not be updated more than once a second. Commands are exe‐
1932 cuted with the tmux global environment set (see the ENVIRONMENT section).
1933 The following variables are available, where appropriate:
1935 Variable name Alias Replaced with
1937 alternate_on If pane is in alternate screen
1938 alternate_saved_x Saved cursor X in alternate screen
1939 alternate_saved_y Saved cursor Y in alternate screen
1940 buffer_created Time buffer created
1941 buffer_name Name of buffer
1942 buffer_sample Sample of start of buffer
1943 buffer_size Size of the specified buffer in bytes
1944 client_activity Time client last had activity
1945 client_created Time client created
1946 client_control_mode 1 if client is in control mode
1947 client_discarded Bytes discarded when client behind
1948 client_height Height of client
1949 client_key_table Current key table
1950 client_last_session Name of the client's last session
1951 client_name Name of client
1952 client_pid PID of client process
1953 client_prefix 1 if prefix key has been pressed
1954 client_readonly 1 if client is readonly
1955 client_session Name of the client's session
1956 client_termname Terminal name of client
1957 client_termtype Terminal type of client
1958 client_tty Pseudo terminal of client
1959 client_utf8 1 if client supports utf8
1960 client_width Width of client
1961 client_written Bytes written to client
1962 command Name of command in use, if any
1963 command_list_name Command name if listing commands
1964 command_list_alias Command alias if listing commands
1965 command_list_usage Command usage if listing commands
1966 cursor_flag Pane cursor flag
1967 cursor_x Cursor X position in pane
1968 cursor_y Cursor Y position in pane
1969 history_bytes Number of bytes in window history
1970 history_limit Maximum window history lines
1971 history_size Size of history in lines
1972 hook Name of running hook, if any
1973 hook_pane ID of pane where hook was run, if any
1974 hook_session ID of session where hook was run, if any
1975 hook_session_name Name of session where hook was run, if
1976 any
1977 hook_window ID of window where hook was run, if any
1978 hook_window_name Name of window where hook was run, if any
1979 host #H Hostname of local host
1980 host_short #h Hostname of local host (no domain name)
1981 insert_flag Pane insert flag
1982 keypad_cursor_flag Pane keypad cursor flag
1983 keypad_flag Pane keypad flag
1984 line Line number in the list
1985 mouse_any_flag Pane mouse any flag
1986 mouse_button_flag Pane mouse button flag
1987 mouse_standard_flag Pane mouse standard flag
1988 mouse_all_flag Pane mouse all flag
1989 pane_active 1 if active pane
1990 pane_at_bottom 1 if pane is at the bottom of window
1991 pane_at_left 1 if pane is at the left of window
1992 pane_at_right 1 if pane is at the right of window
1993 pane_at_top 1 if pane is at the top of window
1994 pane_bottom Bottom of pane
1995 pane_current_command Current command if available
1996 pane_current_path Current path if available
1997 pane_dead 1 if pane is dead
1998 pane_dead_status Exit status of process in dead pane
1999 pane_format 1 if format is for a pane (not assuming
2000 the current)
2001 pane_height Height of pane
2002 pane_id #D Unique pane ID
2003 pane_in_mode If pane is in a mode
2004 pane_input_off If input to pane is disabled
2005 pane_index #P Index of pane
2006 pane_left Left of pane
2007 pane_mode Name of pane mode, if any.
2008 pane_pid PID of first process in pane
2009 pane_pipe 1 if pane is being piped
2010 pane_right Right of pane
2011 pane_search_string Last search string in copy mode
2012 pane_start_command Command pane started with
2013 pane_synchronized If pane is synchronized
2014 pane_tabs Pane tab positions
2015 pane_title #T Title of pane
2016 pane_top Top of pane
2017 pane_tty Pseudo terminal of pane
2018 pane_width Width of pane
2019 pid Server PID
2020 scroll_region_lower Bottom of scroll region in pane
2021 scroll_region_upper Top of scroll region in pane
2022 scroll_position Scroll position in copy mode
2023 selection_present 1 if selection started in copy mode
2024 session_alerts List of window indexes with alerts
2025 session_attached Number of clients session is attached to
2026 session_activity Time of session last activity
2027 session_created Time session created
2028 session_format 1 if format is for a session (not
2029 assuming the current)
2030 session_last_attached Time session last attached
2031 session_group Name of session group
2032 session_group_size Size of session group
2033 session_group_list List of sessions in group
2034 session_grouped 1 if session in a group
2035 session_height Height of session
2036 session_id Unique session ID
2037 session_many_attached 1 if multiple clients attached
2038 session_name #S Name of session
2039 session_stack Window indexes in most recent order
2040 session_width Width of session
2041 session_windows Number of windows in session
2042 socket_path Server socket path
2043 start_time Server start time
2044 version Server version
2045 window_activity Time of window last activity
2046 window_activity_flag 1 if window has activity
2047 window_active 1 if window active
2048 window_bell_flag 1 if window has bell
2049 window_flags #F Window flags
2050 window_format 1 if format is for a window (not assuming
2051 the current)
2052 window_height Height of window
2053 window_id Unique window ID
2054 window_index #I Index of window
2055 window_last_flag 1 if window is the last used
2056 window_layout Window layout description, ignoring
2057 zoomed window panes
2058 window_linked 1 if window is linked across sessions
2059 window_name #W Name of window
2060 window_panes Number of panes in window
2061 window_silence_flag 1 if window has silence alert
2062 window_stack_index Index in session most recent stack
2063 window_visible_layout Window layout description, respecting
2064 zoomed window panes
2065 window_width Width of window
2066 window_zoomed_flag 1 if window is zoomed
2067 wrap_flag Pane wrap flag
2068
2070 tmux distinguishes between names and titles. Windows and sessions have
2071 names, which may be used to specify them in targets and are displayed in
2072 the status line and various lists: the name is the tmux identifier for a
2073 window or session. Only panes have titles. A pane's title is typically
2074 set by the program running inside the pane using an escape sequence (like
2075 it would set the xterm(1) window title in X(7)). Windows themselves do
2076 not have titles - a window's title is the title of its active pane. tmux
2077 itself may set the title of the terminal in which the client is running,
2078 see the set-titles option.
2079 A session's name is set with the new-session and rename-session commands.
2081 A window's name is set with one of:
2082 1. A command argument (such as -n for new-window or new-session).
2084 2. An escape sequence:
2086 $ printf '\033kWINDOW_NAME\033\\'
2088 3. Automatic renaming, which sets the name to the active command in
2090 the window's active pane. See the automatic-rename option.
2091 When a pane is first created, its title is the hostname. A pane's title
2093 can be set via the OSC title setting sequence, for example:
2094 $ printf '\033]2;My Title\033\\'
2096 It can also be modified with the select-pane -T command.
2098
2100 When the server is started, tmux copies the environment into the global
2101 environment; in addition, each session has a session environment. When a
2102 window is created, the session and global environments are merged. If a
2103 variable exists in both, the value from the session environment is used.
2104 The result is the initial environment passed to the new process.
2105 The update-environment session option may be used to update the session
2107 environment from the client when a new session is created or an old reat‐
2108 tached. tmux also initialises the TMUX variable with some internal
2109 information to allow commands to be executed from inside, and the TERM
2110 variable with the correct terminal setting of ‘screen’.
2111 Commands to alter and view the environment are:
2113 set-environment [-gru] [-t target-session] name [value]
2115 (alias: setenv)
2116 Set or unset an environment variable. If -g is used, the change
2117 is made in the global environment; otherwise, it is applied to
2118 the session environment for target-session. The -u flag unsets a
2119 variable. -r indicates the variable is to be removed from the
2120 environment before starting a new process.
2121 show-environment [-gs] [-t target-session] [variable]
2123 (alias: showenv)
2124 Display the environment for target-session or the global environ‐
2125 ment with -g. If variable is omitted, all variables are shown.
2126 Variables removed from the environment are prefixed with ‘-’. If
2127 -s is used, the output is formatted as a set of Bourne shell com‐
2128 mands.
2129
2131 tmux includes an optional status line which is displayed in the bottom
2132 line of each terminal. By default, the status line is enabled (it may be
2133 disabled with the status session option) and contains, from left-to-
2134 right: the name of the current session in square brackets; the window
2135 list; the title of the active pane in double quotes; and the time and
2136 date.
2137 The status line is made of three parts: configurable left and right sec‐
2139 tions (which may contain dynamic content such as the time or output from
2140 a shell command, see the status-left, status-left-length, status-right,
2141 and status-right-length options below), and a central window list. By
2142 default, the window list shows the index, name and (if any) flag of the
2143 windows present in the current session in ascending numerical order. It
2144 may be customised with the window-status-format and
2145 window-status-current-format options. The flag is one of the following
2146 symbols appended to the window name:
2147 Symbol Meaning
2149 * Denotes the current window.
2150 - Marks the last window (previously selected).
2151 # Window activity is monitored and activity has been
2152 detected.
2153 ! Window bells are monitored and a bell has occurred in the
2154 window.
2155 ~ The window has been silent for the monitor-silence
2156 interval.
2157 M The window contains the marked pane.
2158 Z The window's active pane is zoomed.
2159 The # symbol relates to the monitor-activity window option. The window
2161 name is printed in inverted colours if an alert (bell, activity or
2162 silence) is present.
2163 The colour and attributes of the status line may be configured, the
2165 entire status line using the status-style session option and individual
2166 windows using the window-status-style window option.
2167 The status line is automatically refreshed at interval if it has changed,
2169 the interval may be controlled with the status-interval session option.
2170 Commands related to the status line are as follows:
2172 command-prompt [-1i] [-I inputs] [-p prompts] [-t target-client]
2174 [template]
2175 Open the command prompt in a client. This may be used from
2176 inside tmux to execute commands interactively.
2177 If template is specified, it is used as the command. If present,
2179 -I is a comma-separated list of the initial text for each prompt.
2180 If -p is given, prompts is a comma-separated list of prompts
2181 which are displayed in order; otherwise a single prompt is dis‐
2182 played, constructed from template if it is present, or ‘:’ if
2183 not.
2184 Before the command is executed, the first occurrence of the
2186 string ‘%%’ and all occurrences of ‘%1’ are replaced by the
2187 response to the first prompt, all ‘%2’ are replaced with the
2188 response to the second prompt, and so on for further prompts. Up
2189 to nine prompt responses may be replaced (‘%1’ to ‘%9’). ‘%%%’
2190 is like ‘%%’ but any quotation marks are escaped.
2191 -1 makes the prompt only accept one key press, in this case the
2193 resulting input is a single character. -i executes the command
2194 every time the prompt input changes instead of when the user
2195 exits the command prompt.
2196 The following keys have a special meaning in the command prompt,
2198 depending on the value of the status-keys option:
2199 Function vi emacs
2201 Cancel command prompt Escape Escape
2202 Delete current word C-w
2203 Delete entire command d C-u
2204 Delete from cursor to end D C-k
2205 Execute command Enter Enter
2206 Get next command from history Down
2207 Get previous command from history Up
2208 Insert top paste buffer p C-y
2209 Look for completions Tab Tab
2210 Move cursor left h Left
2211 Move cursor right l Right
2212 Move cursor to end $ C-e
2213 Move cursor to next word w M-f
2214 Move cursor to previous word b M-b
2215 Move cursor to start 0 C-a
2216 Transpose characters C-t
2217 confirm-before [-p prompt] [-t target-client] command
2219 (alias: confirm)
2220 Ask for confirmation before executing command. If -p is given,
2221 prompt is the prompt to display; otherwise a prompt is con‐
2222 structed from command. It may contain the special character
2223 sequences supported by the status-left option.
2224 This command works only from inside tmux.
2226 display-message [-p] [-c target-client] [-t target-pane] [message]
2228 (alias: display)
2229 Display a message. If -p is given, the output is printed to std‐
2230 out, otherwise it is displayed in the target-client status line.
2231 The format of message is described in the FORMATS section; infor‐
2232 mation is taken from target-pane if -t is given, otherwise the
2233 active pane for the session attached to target-client.
2234
2236 tmux maintains a set of named paste buffers. Each buffer may be either
2237 explicitly or automatically named. Explicitly named buffers are named
2238 when created with the set-buffer or load-buffer commands, or by renaming
2239 an automatically named buffer with set-buffer -n. Automatically named
2240 buffers are given a name such as ‘buffer0001’, ‘buffer0002’ and so on.
2241 When the buffer-limit option is reached, the oldest automatically named
2242 buffer is deleted. Explicitly named buffers are not subject to
2243 buffer-limit and may be deleted with delete-buffer command.
2244 Buffers may be added using copy-mode or the set-buffer and load-buffer
2246 commands, and pasted into a window using the paste-buffer command. If a
2247 buffer command is used and no buffer is specified, the most recently
2248 added automatically named buffer is assumed.
2249 A configurable history buffer is also maintained for each window. By
2251 default, up to 2000 lines are kept; this can be altered with the
2252 history-limit option (see the set-option command above).
2253 The buffer commands are as follows:
2255 choose-buffer [-NZ] [-F format] [-f filter] [-O sort-order] [-t
2257 target-pane] [template]
2258 Put a pane into buffer mode, where a buffer may be chosen inter‐
2259 actively from a list. -Z zooms the pane. The following keys may
2260 be used in buffer mode:
2261 Key Function
2263 Enter Paste selected buffer
2264 Up Select previous buffer
2265 Down Select next buffer
2266 C-s Search by name or content
2267 n Repeat last search
2268 t Toggle if buffer is tagged
2269 T Tag no buffers
2270 C-t Tag all buffers
2271 p Paste selected buffer
2272 P Paste tagged buffers
2273 d Delete selected buffer
2274 D Delete tagged buffers
2275 f Enter a format to filter items
2276 O Change sort order
2277 v Toggle preview
2278 q Exit mode
2279 After a buffer is chosen, ‘%%’ is replaced by the buffer name in
2281 template and the result executed as a command. If template is
2282 not given, "paste-buffer -b '%%'" is used.
2283 -O specifies the initial sort order: one of ‘time’, ‘name’ or
2285 ‘size’. -f specifies an initial filter: the filter is a format -
2286 if it evaluates to zero, the item in the list is not shown, oth‐
2287 erwise it is shown. If a filter would lead to an empty list, it
2288 is ignored. -F specifies the format for each item in the list.
2289 -N starts without the preview. This command works only if at
2290 least one client is attached.
2291 clear-history [-t target-pane]
2293 (alias: clearhist)
2294 Remove and free the history for the specified pane.
2295 delete-buffer [-b buffer-name]
2297 (alias: deleteb)
2298 Delete the buffer named buffer-name, or the most recently added
2299 automatically named buffer if not specified.
2300 list-buffers [-F format]
2302 (alias: lsb)
2303 List the global buffers. For the meaning of the -F flag, see the
2304 FORMATS section.
2305 load-buffer [-b buffer-name] path
2307 (alias: loadb)
2308 Load the contents of the specified paste buffer from path.
2309 paste-buffer [-dpr] [-b buffer-name] [-s separator] [-t target-pane]
2311 (alias: pasteb)
2312 Insert the contents of a paste buffer into the specified pane.
2313 If not specified, paste into the current one. With -d, also
2314 delete the paste buffer. When output, any linefeed (LF) charac‐
2315 ters in the paste buffer are replaced with a separator, by
2316 default carriage return (CR). A custom separator may be speci‐
2317 fied using the -s flag. The -r flag means to do no replacement
2318 (equivalent to a separator of LF). If -p is specified, paste
2319 bracket control codes are inserted around the buffer if the
2320 application has requested bracketed paste mode.
2321 save-buffer [-a] [-b buffer-name] path
2323 (alias: saveb)
2324 Save the contents of the specified paste buffer to path. The -a
2325 option appends to rather than overwriting the file.
2326 set-buffer [-a] [-b buffer-name] [-n new-buffer-name] data
2328 (alias: setb)
2329 Set the contents of the specified buffer to data. The -a option
2330 appends to rather than overwriting the buffer. The -n option
2331 renames the buffer to new-buffer-name.
2332 show-buffer [-b buffer-name]
2334 (alias: showb)
2335 Display the contents of the specified buffer.
2336
2338 Miscellaneous commands are as follows:
2339 clock-mode [-t target-pane]
2341 Display a large clock.
2342 if-shell [-bF] [-t target-pane] shell-command command [command]
2344 (alias: if)
2345 Execute the first command if shell-command returns success or the
2346 second command otherwise. Before being executed, shell-command
2347 is expanded using the rules specified in the FORMATS section,
2348 including those relevant to target-pane. With -b, shell-command
2349 is run in the background.
2350 If -F is given, shell-command is not executed but considered suc‐
2352 cess if neither empty nor zero (after formats are expanded).
2353 lock-server
2355 (alias: lock)
2356 Lock each client individually by running the command specified by
2357 the lock-command option.
2358 run-shell [-b] [-t target-pane] shell-command
2360 (alias: run)
2361 Execute shell-command in the background without creating a win‐
2362 dow. Before being executed, shell-command is expanded using the
2363 rules specified in the FORMATS section. With -b, the command is
2364 run in the background. After it finishes, any output to stdout
2365 is displayed in copy mode (in the pane specified by -t or the
2366 current pane if omitted). If the command doesn't return success,
2367 the exit status is also displayed.
2368 wait-for [-L | -S | -U] channel
2370 (alias: wait)
2371 When used without options, prevents the client from exiting until
2372 woken using wait-for -S with the same channel. When -L is used,
2373 the channel is locked and any clients that try to lock the same
2374 channel are made to wait until the channel is unlocked with
2375 wait-for -U. This command only works from outside tmux.
2376
2378 tmux understands some unofficial extensions to terminfo(5):
2379 Cs, Cr Set the cursor colour. The first takes a single string argument
2381 and is used to set the colour; the second takes no arguments and
2382 restores the default cursor colour. If set, a sequence such as
2383 this may be used to change the cursor colour from inside tmux:
2384 $ printf '\033]12;red\033\\'
2386 Ss, Se Set or reset the cursor style. If set, a sequence such as this
2388 may be used to change the cursor to an underline:
2389 $ printf '\033[4 q'
2391 If Se is not set, Ss with argument 0 will be used to reset the
2393 cursor style instead.
2394 Tc Indicate that the terminal supports the ‘direct colour’ RGB
2396 escape sequence (for example, \e[38;2;255;255;255m).
2397 If supported, this is used for the OSC initialize colour escape
2399 sequence (which may be enabled by adding the ‘initc’ and ‘ccc’
2400 capabilities to the tmux [22mterminfo(5) entry).
2401 Ms Store the current buffer in the host terminal's selection (clip‐
2403 board). See the set-clipboard option above and the xterm(1) man
2404 page.
2405
2407 tmux offers a textual interface called control mode. This allows appli‐
2408 cations to communicate with tmux using a simple text-only protocol.
2409 In control mode, a client sends tmux commands or command sequences termi‐
2411 nated by newlines on standard input. Each command will produce one block
2412 of output on standard output. An output block consists of a %begin line
2413 followed by the output (which may be empty). The output block ends with
2414 a %end or %error. %begin and matching %end or %error have two arguments:
2415 an integer time (as seconds from epoch) and command number. For example:
2416 %begin 1363006971 2
2418 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
2419 %end 1363006971 2
2420 The refresh-client -C command may be used to set the size of a client in
2422 control mode.
2423 In control mode, tmux outputs notifications. A notification will never
2425 occur inside an output block.
2426 The following notifications are defined:
2428 %client-session-changed client session-id name
2430 The client is now attached to the session with ID session-id,
2431 which is named name.
2432 %exit [reason]
2434 The tmux client is exiting immediately, either because it is not
2435 attached to any session or an error occurred. If present, reason
2436 describes why the client exited.
2437 %layout-change window-id window-layout window-visible-layout window-flags
2439 The layout of a window with ID window-id changed. The new layout
2440 is window-layout. The window's visible layout is
2441 window-visible-layout and the window flags are window-flags.
2442 %output pane-id value
2444 A window pane produced output. value escapes non-printable char‐
2445 acters and backslash as octal \xxx.
2446 %pane-mode-changed pane-id
2448 The pane with ID pane-id has changed mode.
2449 %session-changed session-id name
2451 The client is now attached to the session with ID session-id,
2452 which is named name.
2453 %session-renamed name
2455 The current session was renamed to name.
2456 %session-window-changed session-id window-id
2458 The session with ID session-id changed its active window to the
2459 window with ID window-id.
2460 %sessions-changed
2462 A session was created or destroyed.
2463 %unlinked-window-add window-id
2465 The window with ID window-id was created but is not linked to the
2466 current session.
2467 %window-add window-id
2469 The window with ID window-id was linked to the current session.
2470 %window-close window-id
2472 The window with ID window-id closed.
2473 %window-pane-changed window-id pane-id
2475 The active pane in the window with ID window-id changed to the
2476 pane with ID pane-id.
2477 %window-renamed window-id name
2479 The window with ID window-id was renamed to name.
2480
2482 ~/.tmux.conf Default tmux configuration file.
2483 /etc/tmux.conf System-wide configuration file.
2484
2486 To create a new tmux session running vi(1):
2487 $ tmux new-session vi
2489 Most commands have a shorter form, known as an alias. For new-session,
2491 this is new:
2492 $ tmux new vi
2494 Alternatively, the shortest unambiguous form of a command is accepted.
2496 If there are several options, they are listed:
2497 $ tmux n
2499 ambiguous command: n, could be: new-session, new-window, next-window
2500 Within an active session, a new window may be created by typing ‘C-b c’
2502 (Ctrl followed by the ‘b’ key followed by the ‘c’ key).
2503 Windows may be navigated with: ‘C-b 0’ (to select window 0), ‘C-b 1’ (to
2505 select window 1), and so on; ‘C-b n’ to select the next window; and ‘C-b
2506 p’ to select the previous window.
2507 A session may be detached using ‘C-b d’ (or by an external event such as
2509 ssh(1) disconnection) and reattached with:
2510 $ tmux attach-session
2512 Typing ‘C-b ?’ lists the current key bindings in the current window; up
2514 and down may be used to navigate the list or ‘q’ to exit from it.
2515 Commands to be run when the tmux server is started may be placed in the
2517 ~/.tmux.conf configuration file. Common examples include:
2518 Changing the default prefix key:
2520 set-option -g prefix C-a
2522 unbind-key C-b
2523 bind-key C-a send-prefix
2524 Turning the status line off, or changing its colour:
2526 set-option -g status off
2528 set-option -g status-style bg=blue
2529 Setting other options, such as the default command, or locking after 30
2531 minutes of inactivity:
2532 set-option -g default-command "exec /bin/ksh"
2534 set-option -g lock-after-time 1800
2535 Creating new key bindings:
2537 bind-key b set-option status
2539 bind-key / command-prompt "split-window 'exec man %%'"
2540 bind-key S command-prompt "new-window -n %1 'ssh %1'"
2541
2543 pty(4)
2544
2546 Nicholas Marriott <nicholas.marriott@gmail.com>
2547BSD October 26, 2019 BSD