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 tmux attempts to guess if the terminal is likely to support
89 UTF-8 by checking the first of the LC_ALL, LC_CTYPE and
90 LANG environment variables to be set for the string
91 "UTF-8". This is not always correct: the -u flag explic‐
92 itly informs tmux that 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. This option may be specified mul‐
99 tiple times for increasing verbosity. Log messages will be
100 saved into tmux-client-PID.log and tmux-server-PID.log
101 files in the current directory, where PID is the PID of the
102 server or client process.
103 -V Report the tmux version.
105 command [flags]
107 This specifies one of a set of commands used to control
108 tmux, as described in the following sections. If no com‐
109 mands are specified, the new-session command is assumed.
110
112 tmux may be controlled from an attached client by using a key combination
113 of a prefix key, ‘C-b’ (Ctrl-b) by default, followed by a command key.
114 The default command key bindings are:
116 C-b Send the prefix key (C-b) through to the application.
118 C-o Rotate the panes in the current window forwards.
119 C-z Suspend the tmux client.
120 ! Break the current pane out of the window.
121 " Split the current pane into two, top and bottom.
122 # List all paste buffers.
123 $ Rename the current session.
124 % Split the current pane into two, left and right.
125 & Kill the current window.
126 ' Prompt for a window index to select.
127 ( Switch the attached client to the previous session.
128 ) Switch the attached client to the next session.
129 , Rename the current window.
130 - Delete the most recently copied buffer of text.
131 . Prompt for an index to move the current window.
132 0 to 9 Select windows 0 to 9.
133 : Enter the tmux command prompt.
134 ; Move to the previously active pane.
135 = Choose which buffer to paste interactively from a list.
136 ? List all key bindings.
137 D Choose a client to detach.
138 L Switch the attached client back to the last session.
139 [ Enter copy mode to copy text or view the history.
140 ] Paste the most recently copied buffer of text.
141 c Create a new window.
142 d Detach the current client.
143 f Prompt to search for text in open windows.
144 i Display some information about the current window.
145 l Move to the previously selected window.
146 n Change to the next window.
147 o Select the next pane in the current window.
148 p Change to the previous window.
149 q Briefly display pane indexes.
150 r Force redraw of the attached client.
151 m Mark the current pane (see select-pane -m).
152 M Clear the marked pane.
153 s Select a new session for the attached client interac‐
154 tively.
155 t Show the time.
156 w Choose the current window interactively.
157 x Kill the current pane.
158 z Toggle zoom state of the current pane.
159 { Swap the current pane with the previous pane.
160 } Swap the current pane with the next pane.
161 ~ Show previous messages from tmux, if any.
162 Page Up Enter copy mode and scroll one page up.
163 Up, Down
164 Left, Right
165 Change to the pane above, below, to the left, or to the
166 right of the current pane.
167 M-1 to M-5 Arrange panes in one of the five preset layouts: even-
168 horizontal, even-vertical, main-horizontal, main-verti‐
169 cal, or tiled.
170 Space Arrange the current window in the next preset layout.
171 M-n Move to the next window with a bell or activity marker.
172 M-o Rotate the panes in the current window backwards.
173 M-p Move to the previous window with a bell or activity
174 marker.
175 C-Up, C-Down
176 C-Left, C-Right
177 Resize the current pane in steps of one cell.
178 M-Up, M-Down
179 M-Left, M-Right
180 Resize the current pane in steps of five cells.
181 Key bindings may be changed with the bind-key and unbind-key commands.
183
185 This section contains a list of the commands supported by tmux. Most
186 commands accept the optional -t (and sometimes -s) argument with one of
187 target-client, target-session target-window, or target-pane. These spec‐
188 ify the client, session, window or pane which a command should affect.
189 target-client is the name of the pty(4) file to which the client is con‐
191 nected, for example either of /dev/ttyp1 or ttyp1 for the client attached
192 to /dev/ttyp1. If no client is specified, tmux attempts to work out the
193 client currently in use; if that fails, an error is reported. Clients
194 may be listed with the list-clients command.
195 target-session is tried as, in order:
197 1. A session ID prefixed with a $.
199 2. An exact name of a session (as listed by the list-sessions
201 command).
202 3. The start of a session name, for example ‘mysess’ would match
204 a session named ‘mysession’.
205 4. An fnmatch(3) pattern which is matched against the session
207 name.
208 If the session name is prefixed with an ‘=’, only an exact match is
210 accepted (so ‘=mysess’ will only match exactly ‘mysess’, not
211 ‘mysession’).
212 If a single session is found, it is used as the target session; multiple
214 matches produce an error. If a session is omitted, the current session
215 is used if available; if no current session is available, the most
216 recently used is chosen.
217 target-window (or src-window or dst-window) specifies a window in the
219 form session:window. session follows the same rules as for
220 target-session, and window is looked for in order as:
221 1. A special token, listed below.
223 2. A window index, for example ‘mysession:1’ is window 1 in ses‐
225 sion ‘mysession’.
226 3. A window ID, such as @1.
228 4. An exact window name, such as ‘mysession:mywindow’.
230 5. The start of a window name, such as ‘mysession:mywin’.
232 6. As an fnmatch(3) pattern matched against the window name.
234 Like sessions, a ‘=’ prefix will do an exact match only. An empty window
236 name specifies the next unused index if appropriate (for example the
237 new-window and link-window commands) otherwise the current window in
238 session is chosen.
239 The following special tokens are available to indicate particular win‐
241 dows. Each has a single-character alternative form.
242 Token Meaning
244 {start} ^ The lowest-numbered window
245 {end} $ The highest-numbered window
246 {last} ! The last (previously current) window
247 {next} + The next window by number
248 {previous} - The previous window by number
249 target-pane (or src-pane or dst-pane) may be a pane ID or takes a similar
251 form to target-window but with the optional addition of a period followed
252 by a pane index or pane ID, for example: ‘mysession:mywindow.1’. If the
253 pane index is omitted, the currently active pane in the specified window
254 is used. The following special tokens are available for the pane index:
255 Token Meaning
257 {last} ! The last (previously active) pane
258 {next} + The next pane by number
259 {previous} - The previous pane by number
260 {top} The top pane
261 {bottom} The bottom pane
262 {left} The leftmost pane
263 {right} The rightmost pane
264 {top-left} The top-left pane
265 {top-right} The top-right pane
266 {bottom-left} The bottom-left pane
267 {bottom-right} The bottom-right pane
268 {up-of} The pane above the active pane
269 {down-of} The pane below the active pane
270 {left-of} The pane to the left of the active pane
271 {right-of} The pane to the right of the active pane
272 The tokens ‘+’ and ‘-’ may be followed by an offset, for example:
274 select-window -t:+2
276 In addition, target-session, target-window or target-pane may consist
278 entirely of the token ‘{mouse}’ (alternative form ‘=’) to specify the
279 most recent mouse event (see the MOUSE SUPPORT section) or ‘{marked}’
280 (alternative form ‘~’) to specify the marked pane (see select-pane -m).
281 Sessions, window and panes are each numbered with a unique ID; session
283 IDs are prefixed with a ‘$’, windows with a ‘@’, and panes with a ‘%’.
284 These are unique and are unchanged for the life of the session, window or
285 pane in the tmux server. The pane ID is passed to the child process of
286 the pane in the TMUX_PANE environment variable. IDs may be displayed
287 using the ‘session_id’, ‘window_id’, or ‘pane_id’ formats (see the
288 FORMATS section) and the display-message, list-sessions, list-windows or
289 list-panes commands.
290 shell-command arguments are sh(1) commands. This may be a single argu‐
292 ment passed to the shell, for example:
293 new-window 'vi /etc/passwd'
295 Will run:
297 /bin/sh -c 'vi /etc/passwd'
299 Additionally, the new-window, new-session, split-window, respawn-window
301 and respawn-pane commands allow shell-command to be given as multiple
302 arguments and executed directly (without ‘sh -c’). This can avoid issues
303 with shell quoting. For example:
304 $ tmux new-window vi /etc/passwd
306 Will run vi(1) directly without invoking the shell.
308 command [arguments] refers to a tmux command, passed with the command and
310 arguments separately, for example:
311 bind-key F1 set-window-option force-width 81
313 Or if using sh(1):
315 $ tmux bind-key F1 set-window-option force-width 81
317 Multiple commands may be specified together as part of a command
319 sequence. Each command should be separated by spaces and a semicolon;
320 commands are executed sequentially from left to right and lines ending
321 with a backslash continue on to the next line, except when escaped by
322 another backslash. A literal semicolon may be included by escaping it
323 with a backslash (for example, when specifying a command sequence to
324 bind-key).
325 Example tmux commands include:
327 refresh-client -t/dev/ttyp2
329 rename-session -tfirst newname
331 set-window-option -t:0 monitor-activity on
333 new-window ; split-window -d
335 bind-key R source-file ~/.tmux.conf \; \
337 display-message "source-file done"
338 Or from sh(1):
340 $ tmux kill-window -t :1
342 $ tmux new-window \; split-window -d
344 $ tmux new-session -d 'vi /etc/passwd' \; split-window -d \; attach
346
348 The tmux server manages clients, sessions, windows and panes. Clients
349 are attached to sessions to interact with them, either when they are cre‐
350 ated with the new-session command, or later with the attach-session com‐
351 mand. Each session has one or more windows linked into it. Windows may
352 be linked to multiple sessions and are made up of one or more panes, each
353 of which contains a pseudo terminal. Commands for creating, linking and
354 otherwise manipulating windows are covered in the WINDOWS AND PANES sec‐
355 tion.
356 The following commands are available to manage clients and sessions:
358 attach-session [-dEr] [-c working-directory] [-t target-session]
360 (alias: attach)
361 If run from outside tmux, create a new client in the current ter‐
362 minal and attach it to target-session. If used from inside,
363 switch the current client. If -d is specified, any other clients
364 attached to the session are detached. -r signifies the client is
365 read-only (only keys bound to the detach-client or switch-client
366 commands have any effect)
367 If no server is started, attach-session will attempt to start it;
369 this will fail unless sessions are created in the configuration
370 file.
371 The target-session rules for attach-session are slightly
373 adjusted: if tmux needs to select the most recently used session,
374 it will prefer the most recently used unattached session.
375 -c will set the session working directory (used for new windows)
377 to working-directory.
378 If -E is used, the update-environment option will not be applied.
380 detach-client [-aP] [-s target-session] [-t target-client]
382 (alias: detach)
383 Detach the current client if bound to a key, the client specified
384 with -t, or all clients currently attached to the session speci‐
385 fied by -s. The -a option kills all but the client given with
386 -t. If -P is given, send SIGHUP to the parent process of the
387 client, typically causing it to exit.
388 has-session [-t target-session]
390 (alias: has)
391 Report an error and exit with 1 if the specified session does not
392 exist. If it does exist, exit with 0.
393 kill-server
395 Kill the tmux server and clients and destroy all sessions.
396 kill-session [-aC] [-t target-session]
398 Destroy the given session, closing any windows linked to it and
399 no other sessions, and detaching all clients attached to it. If
400 -a is given, all sessions but the specified one is killed. The
401 -C flag clears alerts (bell, activity, or silence) in all windows
402 linked to the session.
403 list-clients [-F format] [-t target-session]
405 (alias: lsc)
406 List all clients attached to the server. For the meaning of the
407 -F flag, see the FORMATS section. If target-session is speci‐
408 fied, list only clients connected to that session.
409 list-commands
411 (alias: lscm)
412 List the syntax of all commands supported by tmux.
413 list-sessions [-F format]
415 (alias: ls)
416 List all sessions managed by the server. For the meaning of the
417 -F flag, see the FORMATS section.
418 lock-client [-t target-client]
420 (alias: lockc)
421 Lock target-client, see the lock-server command.
422 lock-session [-t target-session]
424 (alias: locks)
425 Lock all clients attached to target-session.
426 new-session [-AdDEP] [-c start-directory] [-F format] [-n window-name]
428 [-s session-name] [-t target-session] [-x width] [-y height]
429 [shell-command]
430 (alias: new)
431 Create a new session with name session-name.
432 The new session is attached to the current terminal unless -d is
434 given. window-name and shell-command are the name of and shell
435 command to execute in the initial window. If -d is used, -x and
436 -y specify the size of the initial window (80 by 24 if not
437 given).
438 If run from a terminal, any termios(4) special characters are
440 saved and used for new windows in the new session.
441 The -A flag makes new-session behave like attach-session if
443 session-name already exists; in this case, -D behaves like -d to
444 attach-session.
445 If -t is given, the new session is grouped with target-session.
447 This means they share the same set of windows - all windows from
448 target-session are linked to the new session, any new windows are
449 linked to both sessions and any windows closed removed from both
450 sessions. The current and previous window and any session
451 options remain independent and either session may be killed with‐
452 out affecting the other. -n and shell-command are invalid if -t
453 is used.
454 The -P option prints information about the new session after it
456 has been created. By default, it uses the format
457 ‘#{session_name}:’ but a different format may be specified with
458 -F.
459 If -E is used, the update-environment option will not be applied.
461 refresh-client [-S] [-t target-client]
463 (alias: refresh)
464 Refresh the current client if bound to a key, or a single client
465 if one is given with -t. If -S is specified, only update the
466 client's status bar.
467 rename-session [-t target-session] new-name
469 (alias: rename)
470 Rename the session to new-name.
471 show-messages [-JT] [-t target-client]
473 (alias: showmsgs)
474 Show client messages or server information. Any messages dis‐
475 played on the status line are saved in a per-client message log,
476 up to a maximum of the limit set by the message-limit server
477 option. With -t, display the log for target-client. -J and -T
478 show debugging information about jobs and terminals.
479 source-file path
481 (alias: source)
482 Execute commands from path.
483 start-server
485 (alias: start)
486 Start the tmux server, if not already running, without creating
487 any sessions.
488 suspend-client [-t target-client]
490 (alias: suspendc)
491 Suspend a client by sending SIGTSTP (tty stop).
492 switch-client [-Elnpr] [-c target-client] [-t target-session] [-T
494 key-table]
495 (alias: switchc)
496 Switch the current session for client target-client to
497 target-session. If -l, -n or -p is used, the client is moved to
498 the last, next or previous session respectively. -r toggles
499 whether a client is read-only (see the attach-session command).
500 If -E is used, update-environment option will not be applied.
502 -T sets the client's key table; the next key from the client will
504 be interpreted from key-table. This may be used to configure
505 multiple prefix keys, or to bind commands to sequences of keys.
506 For example, to make typing ‘abc’ run the list-keys command:
507 bind-key -Ttable2 c list-keys
509 bind-key -Ttable1 b switch-client -Ttable2
510 bind-key -Troot a switch-client -Ttable1
511
513 A tmux window may be in one of several modes. The default permits direct
514 access to the terminal attached to the window. The other is copy mode,
515 which permits a section of a window or its history to be copied to a
516 paste buffer for later insertion into another window. This mode is
517 entered with the copy-mode command, bound to ‘[’ by default. It is also
518 entered when a command that produces output, such as list-keys, is exe‐
519 cuted from a key binding.
520 The keys available depend on whether emacs or vi mode is selected (see
522 the mode-keys option). The following keys are supported as appropriate
523 for the mode:
524 Function vi emacs
526 Append selection A
527 Back to indentation ^ M-m
528 Bottom of history G M-<
529 Clear selection Escape C-g
530 Copy selection Enter M-w
531 Copy to named buffer "
532 Cursor down j Down
533 Cursor left h Left
534 Cursor right l Right
535 Cursor to bottom line L
536 Cursor to middle line M M-r
537 Cursor to top line H M-R
538 Cursor up k Up
539 Delete entire line d C-u
540 Delete/Copy to end of line D C-k
541 End of line $ C-e
542 Go to line : g
543 Half page down C-d M-Down
544 Half page up C-u M-Up
545 Jump again ; ;
546 Jump again in reverse , ,
547 Jump backward F F
548 Jump forward f f
549 Jump to backward T
550 Jump to forward t
551 Next page C-f Page down
552 Next space W
553 Next space, end of word E
554 Next word w
555 Next word end e M-f
556 Other end of selection o
557 Paste buffer p C-y
558 Previous page C-b Page up
559 Previous space B
560 Previous word b M-b
561 Quit mode q Escape
562 Rectangle toggle v R
563 Scroll down C-Down or C-e C-Down
564 Scroll up C-Up or C-y C-Up
565 Search again n n
566 Search again in reverse N N
567 Search backward ? C-r
568 Search forward / C-s
569 Select line V
570 Start of line 0 C-a
571 Start selection Space C-Space
572 Top of history g M->
573 Transpose characters C-t
574 The next and previous word keys use space and the ‘-’, ‘_’ and ‘@’ char‐
576 acters as word delimiters by default, but this can be adjusted by setting
577 the word-separators session option. Next word moves to the start of the
578 next word, next word end to the end of the next word and previous word to
579 the start of the previous word. The three next and previous space keys
580 work similarly but use a space alone as the word separator.
581 The jump commands enable quick movement within a line. For instance,
583 typing ‘f’ followed by ‘/’ will move the cursor to the next ‘/’ character
584 on the current line. A ‘;’ will then jump to the next occurrence.
585 Commands in copy mode may be prefaced by an optional repeat count. With
587 vi key bindings, a prefix is entered using the number keys; with emacs,
588 the Alt (meta) key and a number begins prefix entry. For example, to
589 move the cursor forward by ten words, use ‘M-1 0 M-f’ in emacs mode, and
590 ‘10w’ in vi.
591 Mode key bindings are defined in a set of named tables: vi-edit and
593 emacs-edit for keys used when line editing at the command prompt;
594 vi-choice and emacs-choice for keys used when choosing from lists (such
595 as produced by the choose-window command); and vi-copy and emacs-copy
596 used in copy mode. The tables may be viewed with the list-keys command
597 and keys modified or removed with bind-key and unbind-key. If
598 append-selection, copy-selection, or start-named-buffer are given the -x
599 flag, tmux will not exit copy mode after copying. copy-pipe copies the
600 selection and pipes it to a command. For example the following will bind
601 ‘C-w’ not to exit after copying and ‘C-q’ to copy the selection into /tmp
602 as well as the paste buffer:
603 bind-key -temacs-copy C-w copy-selection -x
605 bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out"
606 The paste buffer key pastes the first line from the top paste buffer on
608 the stack.
609 The synopsis for the copy-mode command is:
611 copy-mode [-Meu] [-t target-pane]
613 Enter copy mode. The -u option scrolls one page up. -M begins a
614 mouse drag (only valid if bound to a mouse key binding, see MOUSE
615 SUPPORT). -e specifies that scrolling to the bottom of the his‐
616 tory (to the visible screen) should exit copy mode. While in
617 copy mode, pressing a key other than those used for scrolling
618 will disable this behaviour. This is intended to allow fast
619 scrolling through a pane's history, for example with:
620 bind PageUp copy-mode -eu
622 Each window displayed by tmux may be split into one or more panes; each
624 pane takes up a certain area of the display and is a separate terminal.
625 A window may be split into panes using the split-window command. Windows
626 may be split horizontally (with the -h flag) or vertically. Panes may be
627 resized with the resize-pane command (bound to ‘C-up’, ‘C-down’ ‘C-left’
628 and ‘C-right’ by default), the current pane may be changed with the
629 select-pane command and the rotate-window and swap-pane commands may be
630 used to swap panes without changing their position. Panes are numbered
631 beginning from zero in the order they are created.
632 A number of preset layouts are available. These may be selected with the
634 select-layout command or cycled with next-layout (bound to ‘Space’ by
635 default); once a layout is chosen, panes within it may be moved and
636 resized as normal.
637 The following layouts are supported:
639 even-horizontal
641 Panes are spread out evenly from left to right across the window.
642 even-vertical
644 Panes are spread evenly from top to bottom.
645 main-horizontal
647 A large (main) pane is shown at the top of the window and the
648 remaining panes are spread from left to right in the leftover
649 space at the bottom. Use the main-pane-height window option to
650 specify the height of the top pane.
651 main-vertical
653 Similar to main-horizontal but the large pane is placed on the
654 left and the others spread from top to bottom along the right.
655 See the main-pane-width window option.
656 tiled Panes are spread out as evenly as possible over the window in
658 both rows and columns.
659 In addition, select-layout may be used to apply a previously used layout
661 - the list-windows command displays the layout of each window in a form
662 suitable for use with select-layout. For example:
663 $ tmux list-windows
665 0: ksh [159x48]
666 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
667 $ tmux select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
668 tmux automatically adjusts the size of the layout for the current window
670 size. Note that a layout cannot be applied to a window with more panes
671 than that from which the layout was originally defined.
672 Commands related to windows and panes are as follows:
674 break-pane [-dP] [-F format] [-s src-pane] [-t dst-window]
676 (alias: breakp)
677 Break src-pane off from its containing window to make it the only
678 pane in dst-window. If -d is given, the new window does not
679 become the current window. The -P option prints information
680 about the new window after it has been created. By default, it
681 uses the format ‘#{session_name}:#{window_index}’ but a different
682 format may be specified with -F.
683 capture-pane [-aepPq] [-b buffer-name] [-E end-line] [-S start-line] [-t
685 target-pane]
686 (alias: capturep)
687 Capture the contents of a pane. If -p is given, the output goes
688 to stdout, otherwise to the buffer specified with -b or a new
689 buffer if omitted. If -a is given, the alternate screen is used,
690 and the history is not accessible. If no alternate screen
691 exists, an error will be returned unless -q is given. If -e is
692 given, the output includes escape sequences for text and back‐
693 ground attributes. -C also escapes non-printable characters as
694 octal \xxx. -J joins wrapped lines and preserves trailing spaces
695 at each line's end. -P captures only any output that the pane
696 has received that is the beginning of an as-yet incomplete escape
697 sequence.
698 -S and -E specify the starting and ending line numbers, zero is
700 the first line of the visible pane and negative numbers are lines
701 in the history. ‘-’ to -S is the start of the history and to -E
702 the end of the visible pane. The default is to capture only the
703 visible contents of the pane.
704 choose-client [-F format] [-t target-window] [template]
706 Put a window into client choice mode, allowing a client to be
707 selected interactively from a list. After a client is chosen,
708 ‘%%’ is replaced by the client pty(4) path in template and the
709 result executed as a command. If template is not given, "detach-
710 client -t '%%'" is used. For the meaning of the -F flag, see the
711 FORMATS section. This command works only if at least one client
712 is attached.
713 choose-session [-F format] [-t target-window] [template]
715 Put a window into session choice mode, where a session may be
716 selected interactively from a list. When one is chosen, ‘%%’ is
717 replaced by the session name in template and the result executed
718 as a command. If template is not given, "switch-client -t '%%'"
719 is used. For the meaning of the -F flag, see the FORMATS sec‐
720 tion. This command works only if at least one client is
721 attached.
722 choose-tree [-suw] [-b session-template] [-c window-template] [-S format]
724 [-W format] [-t target-window]
725 Put a window into tree choice mode, where either sessions or win‐
726 dows may be selected interactively from a list. By default, win‐
727 dows belonging to a session are indented to show their relation‐
728 ship to a session.
729 Note that the choose-window and choose-session commands are wrap‐
731 pers around choose-tree.
732 If -s is given, will show sessions. If -w is given, will show
734 windows.
735 By default, the tree is collapsed and sessions must be expanded
737 to windows with the right arrow key. The -u option will start
738 with all sessions expanded instead.
739 If -b is given, will override the default session command. Note
741 that ‘%%’ can be used and will be replaced with the session name.
742 The default option if not specified is "switch-client -t '%%'".
743 If -c is given, will override the default window command. Like
744 -b, ‘%%’ can be used and will be replaced with the session name
745 and window index. When a window is chosen from the list, the
746 session command is run before the window command.
747 If -S is given will display the specified format instead of the
749 default session format. If -W is given will display the speci‐
750 fied format instead of the default window format. For the mean‐
751 ing of the -s and -w options, see the FORMATS section.
752 This command works only if at least one client is attached.
754 choose-window [-F format] [-t target-window] [template]
756 Put a window into window choice mode, where a window may be cho‐
757 sen interactively from a list. After a window is selected, ‘%%’
758 is replaced by the session name and window index in template and
759 the result executed as a command. If template is not given,
760 "select-window -t '%%'" is used. For the meaning of the -F flag,
761 see the FORMATS section. This command works only if at least one
762 client is attached.
763 display-panes [-t target-client]
765 (alias: displayp)
766 Display a visible indicator of each pane shown by target-client.
767 See the display-panes-time, display-panes-colour, and
768 display-panes-active-colour session options. While the indicator
769 is on screen, a pane may be selected with the ‘0’ to ‘9’ keys.
770 find-window [-CNT] [-F format] [-t target-window] match-string
772 (alias: findw)
773 Search for the fnmatch(3) pattern match-string in window names,
774 titles, and visible content (but not history). The flags control
775 matching behavior: -C matches only visible window contents, -N
776 matches only the window name and -T matches only the window
777 title. The default is -CNT. If only one window is matched,
778 it'll be automatically selected, otherwise a choice list is
779 shown. For the meaning of the -F flag, see the FORMATS section.
780 This command works only if at least one client is attached.
781 join-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane]
783 (alias: joinp)
784 Like split-window, but instead of splitting dst-pane and creating
785 a new pane, split it and move src-pane into the space. This can
786 be used to reverse break-pane. The -b option causes src-pane to
787 be joined to left of or above dst-pane.
788 If -s is omitted and a marked pane is present (see select-pane
790 -m), the marked pane is used rather than the current pane.
791 kill-pane [-a] [-t target-pane]
793 (alias: killp)
794 Destroy the given pane. If no panes remain in the containing
795 window, it is also destroyed. The -a option kills all but the
796 pane given with -t.
797 kill-window [-a] [-t target-window]
799 (alias: killw)
800 Kill the current window or the window at target-window, removing
801 it from any sessions to which it is linked. The -a option kills
802 all but the window given with -t.
803 last-pane [-de] [-t target-window]
805 (alias: lastp)
806 Select the last (previously selected) pane. -e enables or -d
807 disables input to the pane.
808 last-window [-t target-session]
810 (alias: last)
811 Select the last (previously selected) window. If no
812 target-session is specified, select the last window of the cur‐
813 rent session.
814 link-window [-adk] [-s src-window] [-t dst-window]
816 (alias: linkw)
817 Link the window at src-window to the specified dst-window. If
818 dst-window is specified and no such window exists, the src-window
819 is linked there. With -a, the window is moved to the next index
820 up (following windows are moved if necessary). If -k is given
821 and dst-window exists, it is killed, otherwise an error is gener‐
822 ated. If -d is given, the newly linked window is not selected.
823 list-panes [-as] [-F format] [-t target]
825 (alias: lsp)
826 If -a is given, target is ignored and all panes on the server are
827 listed. If -s is given, target is a session (or the current ses‐
828 sion). If neither is given, target is a window (or the current
829 window). For the meaning of the -F flag, see the FORMATS sec‐
830 tion.
831 list-windows [-a] [-F format] [-t target-session]
833 (alias: lsw)
834 If -a is given, list all windows on the server. Otherwise, list
835 windows in the current session or in target-session. For the
836 meaning of the -F flag, see the FORMATS section.
837 move-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane]
839 (alias: movep)
840 Like join-pane, but src-pane and dst-pane may belong to the same
841 window.
842 move-window [-ardk] [-s src-window] [-t dst-window]
844 (alias: movew)
845 This is similar to link-window, except the window at src-window
846 is moved to dst-window. With -r, all windows in the session are
847 renumbered in sequential order, respecting the base-index option.
848 new-window [-adkP] [-c start-directory] [-F format] [-n window-name] [-t
850 target-window] [shell-command]
851 (alias: neww)
852 Create a new window. With -a, the new window is inserted at the
853 next index up from the specified target-window, moving windows up
854 if necessary, otherwise target-window is the new window location.
855 If -d is given, the session does not make the new window the cur‐
857 rent window. target-window represents the window to be created;
858 if the target already exists an error is shown, unless the -k
859 flag is used, in which case it is destroyed. shell-command is
860 the command to execute. If shell-command is not specified, the
861 value of the default-command option is used. -c specifies the
862 working directory in which the new window is created.
863 When the shell command completes, the window closes. See the
865 remain-on-exit option to change this behaviour.
866 The TERM environment variable must be set to “screen” for all
868 programs running inside tmux. New windows will automatically
869 have “TERM=screen” added to their environment, but care must be
870 taken not to reset this in shell start-up files.
871 The -P option prints information about the new window after it
873 has been created. By default, it uses the format
874 ‘#{session_name}:#{window_index}’ but a different format may be
875 specified with -F.
876 next-layout [-t target-window]
878 (alias: nextl)
879 Move a window to the next layout and rearrange the panes to fit.
880 next-window [-a] [-t target-session]
882 (alias: next)
883 Move to the next window in the session. If -a is used, move to
884 the next window with an alert.
885 pipe-pane [-o] [-t target-pane] [shell-command]
887 (alias: pipep)
888 Pipe any output sent by the program in target-pane to a shell
889 command. A pane may only be piped to one command at a time, any
890 existing pipe is closed before shell-command is executed. The
891 shell-command string may contain the special character sequences
892 supported by the status-left option. If no shell-command is
893 given, the current pipe (if any) is closed.
894 The -o option only opens a new pipe if no previous pipe exists,
896 allowing a pipe to be toggled with a single key, for example:
897 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
899 previous-layout [-t target-window]
901 (alias: prevl)
902 Move to the previous layout in the session.
903 previous-window [-a] [-t target-session]
905 (alias: prev)
906 Move to the previous window in the session. With -a, move to the
907 previous window with an alert.
908 rename-window [-t target-window] new-name
910 (alias: renamew)
911 Rename the current window, or the window at target-window if
912 specified, to new-name.
913 resize-pane [-DLMRUZ] [-t target-pane] [-x width] [-y height]
915 [adjustment]
916 (alias: resizep)
917 Resize a pane, up, down, left or right by adjustment with -U, -D,
918 -L or -R, or to an absolute size with -x or -y. The adjustment
919 is given in lines or cells (the default is 1).
920 With -Z, the active pane is toggled between zoomed (occupying the
922 whole of the window) and unzoomed (its normal position in the
923 layout).
924 -M begins mouse resizing (only valid if bound to a mouse key
926 binding, see MOUSE SUPPORT).
927 respawn-pane [-k] [-t target-pane] [shell-command]
929 (alias: respawnp)
930 Reactivate a pane in which the command has exited (see the
931 remain-on-exit window option). If shell-command is not given,
932 the command used when the pane was created is executed. The pane
933 must be already inactive, unless -k is given, in which case any
934 existing command is killed.
935 respawn-window [-k] [-t target-window] [shell-command]
937 (alias: respawnw)
938 Reactivate a window in which the command has exited (see the
939 remain-on-exit window option). If shell-command is not given,
940 the command used when the window was created is executed. The
941 window must be already inactive, unless -k is given, in which
942 case any existing command is killed.
943 rotate-window [-DU] [-t target-window]
945 (alias: rotatew)
946 Rotate the positions of the panes within a window, either upward
947 (numerically lower) with -U or downward (numerically higher).
948 select-layout [-nop] [-t target-window] [layout-name]
950 (alias: selectl)
951 Choose a specific layout for a window. If layout-name is not
952 given, the last preset layout used (if any) is reapplied. -n and
953 -p are equivalent to the next-layout and previous-layout com‐
954 mands. -o applies the last set layout if possible (undoes the
955 most recent layout change).
956 select-pane [-DdegLlMmRU] [-P style] [-t target-pane]
958 (alias: selectp)
959 Make pane target-pane the active pane in window target-window, or
960 set its style (with -P). If one of -D, -L, -R, or -U is used,
961 respectively the pane below, to the left, to the right, or above
962 the target pane is used. -l is the same as using the last-pane
963 command. -e enables or -d disables input to the pane.
964 -m and -M are used to set and clear the marked pane. There is
966 one marked pane at a time, setting a new marked pane clears the
967 last. The marked pane is the default target for -s to join-pane,
968 swap-pane and swap-window.
969 Each pane has a style: by default the window-style and
971 window-active-style options are used, select-pane -P sets the
972 style for a single pane. For example, to set the pane 1 back‐
973 ground to red:
974 select-pane -t:.1 -P 'bg=red'
976 -g shows the current pane style.
978 select-window [-lnpT] [-t target-window]
980 (alias: selectw)
981 Select the window at target-window. -l, -n and -p are equivalent
982 to the last-window, next-window and previous-window commands. If
983 -T is given and the selected window is already the current win‐
984 dow, the command behaves like last-window.
985 split-window [-bdhvP] [-c start-directory] [-l size | -p percentage] [-t
987 target-pane] [shell-command] [-F format]
988 (alias: splitw)
989 Create a new pane by splitting target-pane: -h does a horizontal
990 split and -v a vertical split; if neither is specified, -v is
991 assumed. The -l and -p options specify the size of the new pane
992 in lines (for vertical split) or in cells (for horizontal split),
993 or as a percentage, respectively. The -b option causes the new
994 pane to be created to the left of or above target-pane. All
995 other options have the same meaning as for the new-window com‐
996 mand.
997 swap-pane [-dDU] [-s src-pane] [-t dst-pane]
999 (alias: swapp)
1000 Swap two panes. If -U is used and no source pane is specified
1001 with -s, dst-pane is swapped with the previous pane (before it
1002 numerically); -D swaps with the next pane (after it numerically).
1003 -d instructs tmux not to change the active pane.
1004 If -s is omitted and a marked pane is present (see select-pane
1006 -m), the marked pane is used rather than the current pane.
1007 swap-window [-d] [-s src-window] [-t dst-window]
1009 (alias: swapw)
1010 This is similar to link-window, except the source and destination
1011 windows are swapped. It is an error if no window exists at
1012 src-window.
1013 Like swap-pane, if -s is omitted and a marked pane is present
1015 (see select-pane -m), the window containing the marked pane is
1016 used rather than the current window.
1017 unlink-window [-k] [-t target-window]
1019 (alias: unlinkw)
1020 Unlink target-window. Unless -k is given, a window may be
1021 unlinked only if it is linked to multiple sessions - windows may
1022 not be linked to no sessions; if -k is specified and the window
1023 is linked to only one session, it is unlinked and destroyed.
1024
1026 tmux allows a command to be bound to most keys, with or without a prefix
1027 key. When specifying keys, most represent themselves (for example ‘A’ to
1028 ‘Z’). Ctrl keys may be prefixed with ‘C-’ or ‘^’, and Alt (meta) with
1029 ‘M-’. In addition, the following special key names are accepted: Up,
1030 Down, Left, Right, BSpace, BTab, DC (Delete), End, Enter, Escape, F1 to
1031 F12, Home, IC (Insert), NPage/PageDown/PgDn, PPage/PageUp/PgUp, Space,
1032 and Tab. Note that to bind the ‘"’ or ‘'’ keys, quotation marks are nec‐
1033 essary, for example:
1034 bind-key '"' split-window
1036 bind-key "'" new-window
1037 Commands related to key bindings are as follows:
1039 bind-key [-cnr] [-t mode-table] [-T key-table] key command [arguments]
1041 (alias: bind)
1042 Bind key key to command. Keys are bound in a key table. By
1043 default (without -T), the key is bound in the prefix key table.
1044 This table is used for keys pressed after the prefix key (for
1045 example, by default ‘c’ is bound to new-window in the prefix ta‐
1046 ble, so ‘C-b c’ creates a new window). The root table is used
1047 for keys pressed without the prefix key: binding ‘c’ to
1048 new-window in the root table (not recommended) means a plain ‘c’
1049 will create a new window. -n is an alias for -T root. Keys may
1050 also be bound in custom key tables and the switch-client -T com‐
1051 mand used to switch to them from a key binding. The -r flag
1052 indicates this key may repeat, see the repeat-time option.
1053 If -t is present, key is bound in mode-table: the binding for
1055 command mode with -c or for normal mode without. See the WINDOWS
1056 AND PANES section and the list-keys command for information on
1057 mode key bindings.
1058 To view the default bindings and possible commands, see the
1060 list-keys command.
1061 list-keys [-t mode-table] [-T key-table]
1063 (alias: lsk)
1064 List all key bindings. Without -T all key tables are printed.
1065 With -T only key-table.
1066 With -t, the key bindings in mode-table are listed; this may be
1068 one of: vi-edit, emacs-edit, vi-choice, emacs-choice, vi-copy or
1069 emacs-copy.
1070 send-keys [-lMR] [-t target-pane] key ...
1072 (alias: send)
1073 Send a key or keys to a window. Each argument key is the name of
1074 the key (such as ‘C-a’ or ‘npage’ ) to send; if the string is not
1075 recognised as a key, it is sent as a series of characters. The
1076 -l flag disables key name lookup and sends the keys literally.
1077 All arguments are sent sequentially from first to last. The -R
1078 flag causes the terminal state to be reset.
1079 -M passes through a mouse event (only valid if bound to a mouse
1081 key binding, see MOUSE SUPPORT).
1082 send-prefix [-2] [-t target-pane]
1084 Send the prefix key, or with -2 the secondary prefix key, to a
1085 window as if it was pressed.
1086 unbind-key [-acn] [-t mode-table] [-T key-table] key
1088 (alias: unbind)
1089 Unbind the command bound to key. -c, -n, -T and -t are the same
1090 as for bind-key. If -a is present, all key bindings are removed.
1091
1093 The appearance and behaviour of tmux may be modified by changing the
1094 value of various options. There are three types of option: server
1095 options, session options and window options.
1096 The tmux server has a set of global options which do not apply to any
1098 particular window or session. These are altered with the set-option -s
1099 command, or displayed with the show-options -s command.
1100 In addition, each individual session may have a set of session options,
1102 and there is a separate set of global session options. Sessions which do
1103 not have a particular option configured inherit the value from the global
1104 session options. Session options are set or unset with the set-option
1105 command and may be listed with the show-options command. The available
1106 server and session options are listed under the set-option command.
1107 Similarly, a set of window options is attached to each window, and there
1109 is a set of global window options from which any unset options are inher‐
1110 ited. Window options are altered with the set-window-option command and
1111 can be listed with the show-window-options command. All window options
1112 are documented with the set-window-option command.
1113 tmux also supports user options which are prefixed with a ‘@’. User
1115 options may have any name, so long as they are prefixed with ‘@’, and be
1116 set to any string. For example:
1117 $ tmux setw -q @foo "abc123"
1119 $ tmux showw -v @foo
1120 abc123
1121 Commands which set options are as follows:
1123 set-option [-agoqsuw] [-t target-session | target-window] option value
1125 (alias: set)
1126 Set a window option with -w (equivalent to the set-window-option
1127 command), a server option with -s, otherwise a session option.
1128 If -g is given, the global session or window option is set. The
1129 -u flag unsets an option, so a session inherits the option from
1130 the global options (or with -g, restores a global option to the
1131 default).
1132 The -o flag prevents setting an option that is already set and
1134 the -q flag suppresses errors about unknown or ambiguous options.
1135 With -a, and if the option expects a string or a style, value is
1137 appended to the existing setting. For example:
1138 set -g status-left "foo"
1140 set -ag status-left "bar"
1141 Will result in ‘foobar’. And:
1143 set -g status-style "bg=red"
1145 set -ag status-style "fg=blue"
1146 Will result in a red background and blue foreground. Without -a,
1148 the result would be the default background and a blue foreground.
1149 Available window options are listed under set-window-option.
1151 value depends on the option and may be a number, a string, or a
1153 flag (on, off, or omitted to toggle).
1154 Available server options are:
1156 buffer-limit number
1158 Set the number of buffers; as new buffers are added to
1159 the top of the stack, old ones are removed from the bot‐
1160 tom if necessary to maintain this maximum length.
1161 default-terminal terminal
1163 Set the default terminal for new windows created in this
1164 session - the default value of the TERM environment vari‐
1165 able. For tmux to work correctly, this must be set to
1166 ‘screen’, ‘tmux’ or a derivative of them.
1167 escape-time time
1169 Set the time in milliseconds for which tmux waits after
1170 an escape is input to determine if it is part of a func‐
1171 tion or meta key sequences. The default is 500 millisec‐
1172 onds.
1173 exit-unattached [on | off]
1175 If enabled, the server will exit when there are no
1176 attached clients.
1177 focus-events [on | off]
1179 When enabled, focus events are requested from the termi‐
1180 nal if supported and passed through to applications run‐
1181 ning in tmux. Attached clients should be detached and
1182 attached again after changing this option.
1183 history-file path
1185 If not empty, a file to which tmux will write command
1186 prompt history on exit and load it from on start.
1187 message-limit number
1189 Set the number of error or information messages to save
1190 in the message log for each client. The default is 100.
1191 set-clipboard [on | off]
1193 Attempt to set the terminal clipboard content using the
1194 \e]52;...\007 xterm(1) escape sequences. This option is
1195 on by default if there is an Ms entry in the terminfo(5)
1196 description for the client terminal. Note that this fea‐
1197 ture needs to be enabled in xterm(1) by setting the
1198 resource:
1199 disallowedWindowOps: 20,21,SetXprop
1201 Or changing this property from the xterm(1) interactive
1203 menu when required.
1204 terminal-overrides string
1206 Contains a list of entries which override terminal
1207 descriptions read using terminfo(5). string is a comma-
1208 separated list of items each a colon-separated string
1209 made up of a terminal type pattern (matched using
1210 fnmatch(3)) and a set of name=value entries.
1211 For example, to set the ‘clear’ terminfo(5) entry to
1213 ‘\e[H\e[2J’ for all terminal types and the ‘dch1’ entry
1214 to ‘\e[P’ for the ‘rxvt’ terminal type, the option could
1215 be set to the string:
1216 "*:clear=\e[H\e[2J,rxvt:dch1=\e[P"
1218 The terminal entry value is passed through strunvis(3)
1220 before interpretation. The default value forcibly cor‐
1221 rects the ‘colors’ entry for terminals which support 256
1222 colours:
1223 "*256col*:colors=256,xterm*:XT"
1225 Available session options are:
1227 assume-paste-time milliseconds
1229 If keys are entered faster than one in milliseconds, they
1230 are assumed to have been pasted rather than typed and
1231 tmux key bindings are not processed. The default is one
1232 millisecond and zero disables.
1233 base-index index
1235 Set the base index from which an unused index should be
1236 searched when a new window is created. The default is
1237 zero.
1238 bell-action [any | none | current | other]
1240 Set action on window bell. any means a bell in any win‐
1241 dow linked to a session causes a bell in the current win‐
1242 dow of that session, none means all bells are ignored,
1243 current means only bells in windows other than the cur‐
1244 rent window are ignored and other means bells in the cur‐
1245 rent window are ignored but not those in other windows.
1246 bell-on-alert [on | off]
1248 If on, ring the terminal bell when an alert occurs.
1249 default-command shell-command
1251 Set the command used for new windows (if not specified
1252 when the window is created) to shell-command, which may
1253 be any sh(1) command. The default is an empty string,
1254 which instructs tmux to create a login shell using the
1255 value of the default-shell option.
1256 default-shell path
1258 Specify the default shell. This is used as the login
1259 shell for new windows when the default-command option is
1260 set to empty, and must be the full path of the exe‐
1261 cutable. When started tmux tries to set a default value
1262 from the first suitable of the SHELL environment vari‐
1263 able, the shell returned by getpwuid(3), or /bin/sh.
1264 This option should be configured when tmux is used as a
1265 login shell.
1266 destroy-unattached [on | off]
1268 If enabled and the session is no longer attached to any
1269 clients, it is destroyed.
1270 detach-on-destroy [on | off]
1272 If on (the default), the client is detached when the ses‐
1273 sion it is attached to is destroyed. If off, the client
1274 is switched to the most recently active of the remaining
1275 sessions.
1276 display-panes-active-colour colour
1278 Set the colour used by the display-panes command to show
1279 the indicator for the active pane.
1280 display-panes-colour colour
1282 Set the colour used by the display-panes command to show
1283 the indicators for inactive panes.
1284 display-panes-time time
1286 Set the time in milliseconds for which the indicators
1287 shown by the display-panes command appear.
1288 display-time time
1290 Set the amount of time for which status line messages and
1291 other on-screen indicators are displayed. If set to 0,
1292 messages and indicators are displayed until a key is
1293 pressed. time is in milliseconds.
1294 history-limit lines
1296 Set the maximum number of lines held in window history.
1297 This setting applies only to new windows - existing win‐
1298 dow histories are not resized and retain the limit at the
1299 point they were created.
1300 key-table key-table
1302 Set the default key table to key-table instead of root.
1303 lock-after-time number
1305 Lock the session (like the lock-session command) after
1306 number seconds of inactivity. The default is not to lock
1307 (set to 0).
1308 lock-command shell-command
1310 Command to run when locking each client. The default is
1311 to run lock(1) with -np.
1312 message-command-style style
1314 Set status line message command style, where style is a
1315 comma-separated list of characteristics to be specified.
1316 These may be ‘bg=colour’ to set the background colour,
1318 ‘fg=colour’ to set the foreground colour, and a list of
1319 attributes as specified below.
1320 The colour is one of: black, red, green, yellow, blue,
1322 magenta, cyan, white, aixterm bright variants (if sup‐
1323 ported: brightred, brightgreen, and so on), colour0 to
1324 colour255 from the 256-colour set, default, or a hexadec‐
1325 imal RGB string such as ‘#ffffff’, which chooses the
1326 closest match from the default 256-colour set.
1327 The attributes is either none or a comma-delimited list
1329 of one or more of: bright (or bold), dim, underscore,
1330 blink, reverse, hidden, or italics, to turn an attribute
1331 on, or an attribute prefixed with ‘no’ to turn one off.
1332 Examples are:
1334 fg=yellow,bold,underscore,blink
1336 bg=black,fg=default,noreverse
1337 With the -a flag to the set-option command the new style
1339 is added otherwise the existing style is replaced.
1340 message-style style
1342 Set status line message style. For how to specify style,
1343 see the message-command-style option.
1344 mouse [on | off]
1346 If on, tmux captures the mouse and allows mouse events to
1347 be bound as key bindings. See the MOUSE SUPPORT section
1348 for details.
1349 prefix key
1351 Set the key accepted as a prefix key. In addition to the
1352 standard keys described under KEY BINDINGS, prefix can be
1353 set to the special key ‘None’ to set no prefix.
1354 prefix2 key
1356 Set a secondary key accepted as a prefix key. Like
1357 prefix, prefix2 can be set to ‘None’.
1358 renumber-windows [on | off]
1360 If on, when a window is closed in a session, automati‐
1361 cally renumber the other windows in numerical order.
1362 This respects the base-index option if it has been set.
1363 If off, do not renumber the windows.
1364 repeat-time time
1366 Allow multiple commands to be entered without pressing
1367 the prefix-key again in the specified time milliseconds
1368 (the default is 500). Whether a key repeats may be set
1369 when it is bound using the -r flag to bind-key. Repeat
1370 is enabled for the default keys bound to the resize-pane
1371 command.
1372 set-remain-on-exit [on | off]
1374 Set the remain-on-exit window option for any windows
1375 first created in this session. When this option is true,
1376 windows in which the running program has exited do not
1377 close, instead remaining open but inactivate. Use the
1378 respawn-window command to reactivate such a window, or
1379 the kill-window command to destroy it.
1380 set-titles [on | off]
1382 Attempt to set the client terminal title using the tsl
1383 and fsl terminfo(5) entries if they exist. tmux automat‐
1384 ically sets these to the \e]0;...\007 sequence if the
1385 terminal appears to be xterm(1). This option is off by
1386 default.
1387 set-titles-string string
1389 String used to set the window title if set-titles is on.
1390 Formats are expanded, see the FORMATS section.
1391 status [on | off]
1393 Show or hide the status line.
1394 status-interval interval
1396 Update the status bar every interval seconds. By
1397 default, updates will occur every 15 seconds. A setting
1398 of zero disables redrawing at interval.
1399 status-justify [left | centre | right]
1401 Set the position of the window list component of the sta‐
1402 tus line: left, centre or right justified.
1403 status-keys [vi | emacs]
1405 Use vi or emacs-style key bindings in the status line,
1406 for example at the command prompt. The default is emacs,
1407 unless the VISUAL or EDITOR environment variables are set
1408 and contain the string ‘vi’.
1409 status-left string
1411 Display string (by default the session name) to the left
1412 of the status bar. string will be passed through
1413 strftime(3) and formats (see FORMATS) will be expanded.
1414 It may also contain any of the following special charac‐
1415 ter sequences:
1416 Character pair Replaced with
1418 #[attributes] Colour or attribute change
1419 ## A literal ‘#’
1420 For details on how the names and titles can be set see
1422 the NAMES AND TITLES section. For a list of allowed
1423 attributes see the message-command-style option.
1424 Examples are:
1426 #(sysctl vm.loadavg)
1428 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
1429 The default is ‘[#S] ’.
1431 status-left-length length
1433 Set the maximum length of the left component of the sta‐
1434 tus bar. The default is 10.
1435 status-left-style style
1437 Set the style of the left part of the status line. For
1438 how to specify style, see the message-command-style
1439 option.
1440 status-position [top | bottom]
1442 Set the position of the status line.
1443 status-right string
1445 Display string to the right of the status bar. By
1446 default, the current window title in double quotes, the
1447 date and the time are shown. As with status-left, string
1448 will be passed to strftime(3) and character pairs are
1449 replaced.
1450 status-right-length length
1452 Set the maximum length of the right component of the sta‐
1453 tus bar. The default is 40.
1454 status-right-style style
1456 Set the style of the right part of the status line. For
1457 how to specify style, see the message-command-style
1458 option.
1459 status-style style
1461 Set status line style. For how to specify style, see the
1462 message-command-style option.
1463 update-environment variables
1465 Set a space-separated string containing a list of envi‐
1466 ronment variables to be copied into the session environ‐
1467 ment when a new session is created or an existing session
1468 is attached. Any variables that do not exist in the
1469 source environment are set to be removed from the session
1470 environment (as if -r was given to the set-environment
1471 command). The default is "DISPLAY SSH_ASKPASS
1472 SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID XAU‐
1473 THORITY".
1474 visual-activity [on | off]
1476 If on, display a status line message when activity occurs
1477 in a window for which the monitor-activity window option
1478 is enabled.
1479 visual-bell [on | off]
1481 If this option is on, a message is shown on a bell
1482 instead of it being passed through to the terminal (which
1483 normally makes a sound). Also see the bell-action
1484 option.
1485 visual-silence [on | off]
1487 If monitor-silence is enabled, prints a message after the
1488 interval has expired on a given window.
1489 word-separators string
1491 Sets the session's conception of what characters are con‐
1492 sidered word separators, for the purposes of the next and
1493 previous word commands in copy mode. The default is
1494 ‘ -_@’.
1495 set-window-option [-agoqu] [-t target-window] option value
1497 (alias: setw)
1498 Set a window option. The -a, -g, -o, -q and -u flags work simi‐
1499 larly to the set-option command.
1500 Supported window options are:
1502 aggressive-resize [on | off]
1504 Aggressively resize the chosen window. This means that
1505 tmux will resize the window to the size of the smallest
1506 session for which it is the current window, rather than
1507 the smallest session to which it is attached. The window
1508 may resize when the current window is changed on another
1509 sessions; this option is good for full-screen programs
1510 which support SIGWINCH and poor for interactive programs
1511 such as shells.
1512 allow-rename [on | off]
1514 Allow programs to change the window name using a terminal
1515 escape sequence (\ek...\e\\). The default is on.
1516 alternate-screen [on | off]
1518 This option configures whether programs running inside
1519 tmux may use the terminal alternate screen feature, which
1520 allows the smcup and rmcup terminfo(5) capabilities. The
1521 alternate screen feature preserves the contents of the
1522 window when an interactive application starts and
1523 restores it on exit, so that any output visible before
1524 the application starts reappears unchanged after it
1525 exits. The default is on.
1526 automatic-rename [on | off]
1528 Control automatic window renaming. When this setting is
1529 enabled, tmux will rename the window automatically using
1530 the format specified by automatic-rename-format. This
1531 flag is automatically disabled for an individual window
1532 when a name is specified at creation with new-window or
1533 new-session, or later with rename-window, or with a ter‐
1534 minal escape sequence. It may be switched off globally
1535 with:
1536 set-window-option -g automatic-rename off
1538 automatic-rename-format format
1540 The format (see FORMATS) used when the automatic-rename
1541 option is enabled.
1542 clock-mode-colour colour
1544 Set clock colour.
1545 clock-mode-style [12 | 24]
1547 Set clock hour format.
1548 force-height height
1550 force-width width
1551 Prevent tmux from resizing a window to greater than width
1552 or height. A value of zero restores the default unlim‐
1553 ited setting.
1554 main-pane-height height
1556 main-pane-width width
1557 Set the width or height of the main (left or top) pane in
1558 the main-horizontal or main-vertical layouts.
1559 mode-keys [vi | emacs]
1561 Use vi or emacs-style key bindings in copy and choice
1562 modes. As with the status-keys option, the default is
1563 emacs, unless VISUAL or EDITOR contains ‘vi’.
1564 mode-style style
1566 Set window modes style. For how to specify style, see
1567 the message-command-style option.
1568 monitor-activity [on | off]
1570 Monitor for activity in the window. Windows with activ‐
1571 ity are highlighted in the status line.
1572 monitor-silence [interval]
1574 Monitor for silence (no activity) in the window within
1575 interval seconds. Windows that have been silent for the
1576 interval are highlighted in the status line. An interval
1577 of zero disables the monitoring.
1578 other-pane-height height
1580 Set the height of the other panes (not the main pane) in
1581 the main-horizontal layout. If this option is set to 0
1582 (the default), it will have no effect. If both the
1583 main-pane-height and other-pane-height options are set,
1584 the main pane will grow taller to make the other panes
1585 the specified height, but will never shrink to do so.
1586 other-pane-width width
1588 Like other-pane-height, but set the width of other panes
1589 in the main-vertical layout.
1590 pane-active-border-style style
1592 Set the pane border style for the currently active pane.
1593 For how to specify style, see the message-command-style
1594 option. Attributes are ignored.
1595 pane-base-index index
1597 Like base-index, but set the starting index for pane num‐
1598 bers.
1599 pane-border-style style
1601 Set the pane border style for panes aside from the active
1602 pane. For how to specify style, see the
1603 message-command-style option. Attributes are ignored.
1604 remain-on-exit [on | off]
1606 A window with this flag set is not destroyed when the
1607 program running in it exits. The window may be reacti‐
1608 vated with the respawn-window command.
1609 synchronize-panes [on | off]
1611 Duplicate input to any pane to all other panes in the
1612 same window (only for panes that are not in any special
1613 mode).
1614 window-active-style style
1616 Set the style for the window's active pane. For how to
1617 specify style, see the message-command-style option.
1618 window-status-activity-style style
1620 Set status line style for windows with an activity alert.
1621 For how to specify style, see the message-command-style
1622 option.
1623 window-status-bell-style style
1625 Set status line style for windows with a bell alert. For
1626 how to specify style, see the message-command-style
1627 option.
1628 window-status-current-format string
1630 Like window-status-format, but is the format used when
1631 the window is the current window.
1632 window-status-current-style style
1634 Set status line style for the currently active window.
1635 For how to specify style, see the message-command-style
1636 option.
1637 window-status-format string
1639 Set the format in which the window is displayed in the
1640 status line window list. See the status-left option for
1641 details of special character sequences available. The
1642 default is ‘#I:#W#F’.
1643 window-status-last-style style
1645 Set status line style for the last active window. For
1646 how to specify style, see the message-command-style
1647 option.
1648 window-status-separator string
1650 Sets the separator drawn between windows in the status
1651 line. The default is a single space character.
1652 window-status-style style
1654 Set status line style for a single window. For how to
1655 specify style, see the message-command-style option.
1656 window-style style
1658 Set the default window style. For how to specify style,
1659 see the message-command-style option.
1660 xterm-keys [on | off]
1662 If this option is set, tmux will generate xterm(1) -style
1663 function key sequences; these have a number included to
1664 indicate modifiers such as Shift, Alt or Ctrl. The
1665 default is off.
1666 wrap-search [on | off]
1668 If this option is set, searches will wrap around the end
1669 of the pane contents. The default is on.
1670 show-options [-gqsvw] [-t target-session | target-window] [option]
1672 (alias: show)
1673 Show the window options (or a single window option if given) with
1674 -w (equivalent to show-window-options), the server options with
1675 -s, otherwise the session options for target session. Global
1676 session or window options are listed if -g is used. -v shows
1677 only the option value, not the name. If -q is set, no error will
1678 be returned if option is unset.
1679 show-window-options [-gv] [-t target-window] [option]
1681 (alias: showw)
1682 List the window options or a single option for target-window, or
1683 the global window options if -g is used. -v shows only the
1684 option value, not the name.
1685
1687 tmux allows commands to run on various triggers, called hooks. Each hook
1688 has a name. The following hooks are available:
1689 alert-activity Run when a window has activity. See monitor-activity.
1691 alert-bell Run when a window has received a bell.
1693 alert-silence Run when a window has been silent. See
1695 monitor-silence.
1696 client-attached Run when a client is attached.
1698 client-detached Run when a client is detached
1700 client-resized Run when a client is resized.
1702 pane-died Run when the program running in a pane exits, but
1704 remain-on-exit is on so the pane has not closed.
1705 pane-exited Run when the program running in a pane exits.
1707 Hooks are managed with these commands:
1709 set-hook [-g] [-t target-session] hook-name command
1711 Sets hook hook-name to command. If -g is given, hook-name is
1712 added to the global list of hooks, otherwise it is added to the
1713 session hooks (for target-session with -t). Like options, ses‐
1714 sion hooks inherit from the global ones.
1715 show-hooks [-g] [-t target-session]
1717 Shows the global list of hooks with -g, otherwise the session
1718 hooks.
1719
1721 If the mouse option is on (the default is off), tmux allows mouse events
1722 to be bound as keys. The name of each key is made up of a mouse event
1723 (such as ‘MouseUp1’) and a location suffix (one of ‘Pane’ for the con‐
1724 tents of a pane, ‘Border’ for a pane border or ‘Status’ for the status
1725 line). The following mouse events are available:
1726 MouseDown1 MouseUp1 MouseDrag1 MouseDragEnd1
1728 MouseDown2 MouseUp2 MouseDrag2 MouseDragEnd2
1729 MouseDown3 MouseUp3 MouseDrag3 MouseDragEnd3
1730 WheelUp WheelDown
1731 Each should be suffixed with a location, for example ‘MouseDown1Status’.
1733 The special token ‘{mouse}’ or ‘=’ may be used as target-window or
1735 target-pane in commands bound to mouse key bindings. It resolves to the
1736 window or pane over which the mouse event took place (for example, the
1737 window in the status line over which button 1 was released for a
1738 ‘MouseUp1Status’ binding, or the pane over which the wheel was scrolled
1739 for a ‘WheelDownPane’ binding).
1740 The send-keys -M flag may be used to forward a mouse event to a pane.
1742 The default key bindings allow the mouse to be used to select and resize
1744 panes, to copy text and to change window using the status line. These
1745 take effect if the mouse option is turned on.
1746
1748 Certain commands accept the -F flag with a format argument. This is a
1749 string which controls the output format of the command. Replacement
1750 variables are enclosed in ‘#{’ and ‘}’, for example ‘#{session_name}’.
1751 The possible variables are listed in the table below, or the name of a
1752 tmux option may be used for an option's value. Some variables have a
1753 shorter alias such as ‘#S’, and ‘##’ is replaced by a single ‘#’.
1754 Conditionals are available by prefixing with ‘?’ and separating two
1756 alternatives with a comma; if the specified variable exists and is not
1757 zero, the first alternative is chosen, otherwise the second is used. For
1758 example ‘#{?session_attached,attached,not attached}’ will include the
1759 string ‘attached’ if the session is attached and the string ‘not
1760 attached’ if it is unattached, or ‘#{?automatic-rename,yes,no}’ will
1761 include ‘yes’ if automatic-rename is enabled, or ‘no’ if not.
1762 A limit may be placed on the length of the resultant string by prefixing
1764 it by an ‘=’, a number and a colon. Positive numbers count from the
1765 start of the string and negative from the end, so ‘#{=5:pane_title}’ will
1766 include at most the first 5 characters of the pane title, or
1767 ‘#{=-5:pane_title}’ the last 5 characters. Prefixing a time variable
1768 with ‘t:’ will convert it to a string, so if ‘#{window_activity}’ gives
1769 ‘1445765102’, ‘#{t:window_activity}’ gives ‘Sun Oct 25 09:25:02 2015’.
1770 The ‘b:’ and ‘d:’ prefixes are basename(3) and dirname(3) of the variable
1771 respectively. A prefix of the form ‘s/foo/bar/:’ will substitute ‘foo’
1772 with ‘bar’ throughout.
1773 In addition, the first line of a shell command's output may be inserted
1775 using ‘#()’. For example, ‘#(uptime)’ will insert the system's uptime.
1776 When constructing formats, tmux does not wait for ‘#()’ commands to fin‐
1777 ish; instead, the previous result from running the same command is used,
1778 or a placeholder if the command has not been run before. Commands are
1779 executed with the tmux global environment set (see the ENVIRONMENT sec‐
1780 tion).
1781 The following variables are available, where appropriate:
1783 Variable name Alias Replaced with
1785 alternate_on If pane is in alternate screen
1786 alternate_saved_x Saved cursor X in alternate screen
1787 alternate_saved_y Saved cursor Y in alternate screen
1788 buffer_sample Sample of start of buffer
1789 buffer_size Size of the specified buffer in bytes
1790 client_activity Integer time client last had activity
1791 client_created Integer time client created
1792 client_control_mode 1 if client is in control mode
1793 client_height Height of client
1794 client_key_table Current key table
1795 client_last_session Name of the client's last session
1796 client_pid PID of client process
1797 client_prefix 1 if prefix key has been pressed
1798 client_readonly 1 if client is readonly
1799 client_session Name of the client's session
1800 client_termname Terminal name of client
1801 client_tty Pseudo terminal of client
1802 client_utf8 1 if client supports utf8
1803 client_width Width of client
1804 command_name Name of command in use, if any
1805 cursor_flag Pane cursor flag
1806 cursor_x Cursor X position in pane
1807 cursor_y Cursor Y position in pane
1808 history_bytes Number of bytes in window history
1809 history_limit Maximum window history lines
1810 history_size Size of history in bytes
1811 host #H Hostname of local host
1812 host_short #h Hostname of local host (no domain name)
1813 insert_flag Pane insert flag
1814 keypad_cursor_flag Pane keypad cursor flag
1815 keypad_flag Pane keypad flag
1816 line Line number in the list
1817 mouse_any_flag Pane mouse any flag
1818 mouse_button_flag Pane mouse button flag
1819 mouse_standard_flag Pane mouse standard flag
1820 pane_active 1 if active pane
1821 pane_bottom Bottom of pane
1822 pane_current_command Current command if available
1823 pane_current_path Current path if available
1824 pane_dead 1 if pane is dead
1825 pane_dead_status Exit status of process in dead pane
1826 pane_height Height of pane
1827 pane_id #D Unique pane ID
1828 pane_in_mode If pane is in a mode
1829 pane_input_off If input to pane is disabled
1830 pane_index #P Index of pane
1831 pane_left Left of pane
1832 pane_pid PID of first process in pane
1833 pane_right Right of pane
1834 pane_start_command Command pane started with
1835 pane_synchronized If pane is synchronized
1836 pane_tabs Pane tab positions
1837 pane_title #T Title of pane
1838 pane_top Top of pane
1839 pane_tty Pseudo terminal of pane
1840 pane_width Width of pane
1841 pid Server PID
1842 scroll_region_lower Bottom of scroll region in pane
1843 scroll_region_upper Top of scroll region in pane
1844 scroll_position Scroll position in copy mode
1845 session_alerts List of window indexes with alerts
1846 session_attached Number of clients session is attached to
1847 session_activity Integer time of session last activity
1848 session_created Integer time session created
1849 session_last_attached Integer time session last attached
1850 session_group Number of session group
1851 session_grouped 1 if session in a group
1852 session_height Height of session
1853 session_id Unique session ID
1854 session_many_attached 1 if multiple clients attached
1855 session_name #S Name of session
1856 session_width Width of session
1857 session_windows Number of windows in session
1858 socket_path Server socket path
1859 start_time Server start time
1860 window_activity Integer time of window last activity
1861 window_active 1 if window active
1862 window_bell_flag 1 if window has bell
1863 window_find_matches Matched data from the find-window
1864 window_flags #F Window flags
1865 window_height Height of window
1866 window_id Unique window ID
1867 window_index #I Index of window
1868 window_last_flag 1 if window is the last used
1869 window_layout Window layout description, ignoring
1870 zoomed window panes
1871 window_linked 1 if window is linked across sessions
1872 window_name #W Name of window
1873 window_panes Number of panes in window
1874 window_silence_flag 1 if window has silence alert
1875 window_visible_layout Window layout description, respecting
1876 zoomed window panes
1877 window_width Width of window
1878 window_zoomed_flag 1 if window is zoomed
1879 wrap_flag Pane wrap flag
1880
1882 tmux distinguishes between names and titles. Windows and sessions have
1883 names, which may be used to specify them in targets and are displayed in
1884 the status line and various lists: the name is the tmux identifier for a
1885 window or session. Only panes have titles. A pane's title is typically
1886 set by the program running inside the pane and is not modified by tmux.
1887 It is the same mechanism used to set for example the xterm(1) window
1888 title in an X(7) window manager. Windows themselves do not have titles -
1889 a window's title is the title of its active pane. tmux itself may set
1890 the title of the terminal in which the client is running, see the
1891 set-titles option.
1892 A session's name is set with the new-session and rename-session commands.
1894 A window's name is set with one of:
1895 1. A command argument (such as -n for new-window or new-session).
1897 2. An escape sequence:
1899 $ printf '\033kWINDOW_NAME\033\\'
1901 3. Automatic renaming, which sets the name to the active command in
1903 the window's active pane. See the automatic-rename option.
1904 When a pane is first created, its title is the hostname. A pane's title
1906 can be set via the OSC title setting sequence, for example:
1907 $ printf '\033]2;My Title\033\\'
1909
1911 When the server is started, tmux copies the environment into the global
1912 environment; in addition, each session has a session environment. When a
1913 window is created, the session and global environments are merged. If a
1914 variable exists in both, the value from the session environment is used.
1915 The result is the initial environment passed to the new process.
1916 The update-environment session option may be used to update the session
1918 environment from the client when a new session is created or an old reat‐
1919 tached. tmux also initialises the TMUX variable with some internal
1920 information to allow commands to be executed from inside, and the TERM
1921 variable with the correct terminal setting of ‘screen’.
1922 Commands to alter and view the environment are:
1924 set-environment [-gru] [-t target-session] name [value]
1926 (alias: setenv)
1927 Set or unset an environment variable. If -g is used, the change
1928 is made in the global environment; otherwise, it is applied to
1929 the session environment for target-session. The -u flag unsets a
1930 variable. -r indicates the variable is to be removed from the
1931 environment before starting a new process.
1932 show-environment [-gs] [-t target-session] [variable]
1934 (alias: showenv)
1935 Display the environment for target-session or the global environ‐
1936 ment with -g. If variable is omitted, all variables are shown.
1937 Variables removed from the environment are prefixed with ‘-’. If
1938 -s is used, the output is formatted as a set of Bourne shell com‐
1939 mands.
1940
1942 tmux includes an optional status line which is displayed in the bottom
1943 line of each terminal. By default, the status line is enabled (it may be
1944 disabled with the status session option) and contains, from left-to-
1945 right: the name of the current session in square brackets; the window
1946 list; the title of the active pane in double quotes; and the time and
1947 date.
1948 The status line is made of three parts: configurable left and right sec‐
1950 tions (which may contain dynamic content such as the time or output from
1951 a shell command, see the status-left, status-left-length, status-right,
1952 and status-right-length options below), and a central window list. By
1953 default, the window list shows the index, name and (if any) flag of the
1954 windows present in the current session in ascending numerical order. It
1955 may be customised with the window-status-format and
1956 window-status-current-format options. The flag is one of the following
1957 symbols appended to the window name:
1958 Symbol Meaning
1960 * Denotes the current window.
1961 - Marks the last window (previously selected).
1962 # Window is monitored and activity has been detected.
1963 ! A bell has occurred in the window.
1964 ~ The window has been silent for the monitor-silence
1965 interval.
1966 M The window contains the marked pane.
1967 Z The window's active pane is zoomed.
1968 The # symbol relates to the monitor-activity window option. The window
1970 name is printed in inverted colours if an alert (bell, activity or
1971 silence) is present.
1972 The colour and attributes of the status line may be configured, the
1974 entire status line using the status-style session option and individual
1975 windows using the window-status-style window option.
1976 The status line is automatically refreshed at interval if it has changed,
1978 the interval may be controlled with the status-interval session option.
1979 Commands related to the status line are as follows:
1981 command-prompt [-I inputs] [-p prompts] [-t target-client] [template]
1983 Open the command prompt in a client. This may be used from
1984 inside tmux to execute commands interactively.
1985 If template is specified, it is used as the command. If present,
1987 -I is a comma-separated list of the initial text for each prompt.
1988 If -p is given, prompts is a comma-separated list of prompts
1989 which are displayed in order; otherwise a single prompt is dis‐
1990 played, constructed from template if it is present, or ‘:’ if
1991 not.
1992 Both inputs and prompts may contain the special character
1994 sequences supported by the status-left option.
1995 Before the command is executed, the first occurrence of the
1997 string ‘%%’ and all occurrences of ‘%1’ are replaced by the
1998 response to the first prompt, the second ‘%%’ and all ‘%2’ are
1999 replaced with the response to the second prompt, and so on for
2000 further prompts. Up to nine prompt responses may be replaced
2001 (‘%1’ to ‘%9’).
2002 confirm-before [-p prompt] [-t target-client] command
2004 (alias: confirm)
2005 Ask for confirmation before executing command. If -p is given,
2006 prompt is the prompt to display; otherwise a prompt is con‐
2007 structed from command. It may contain the special character
2008 sequences supported by the status-left option.
2009 This command works only from inside tmux.
2011 display-message [-p] [-c target-client] [-t target-pane] [message]
2013 (alias: display)
2014 Display a message. If -p is given, the output is printed to std‐
2015 out, otherwise it is displayed in the target-client status line.
2016 The format of message is described in the FORMATS section; infor‐
2017 mation is taken from target-pane if -t is given, otherwise the
2018 active pane for the session attached to target-client.
2019
2021 tmux maintains a set of named paste buffers. Each buffer may be either
2022 explicitly or automatically named. Explicitly named buffers are named
2023 when created with the set-buffer or load-buffer commands, or by renaming
2024 an automatically named buffer with set-buffer -n. Automatically named
2025 buffers are given a name such as ‘buffer0001’, ‘buffer0002’ and so on.
2026 When the buffer-limit option is reached, the oldest automatically named
2027 buffer is deleted. Explicitly named are not subject to buffer-limit and
2028 may be deleted with delete-buffer command.
2029 Buffers may be added using copy-mode or the set-buffer and load-buffer
2031 commands, and pasted into a window using the paste-buffer command. If a
2032 buffer command is used and no buffer is specified, the most recently
2033 added automatically named buffer is assumed.
2034 A configurable history buffer is also maintained for each window. By
2036 default, up to 2000 lines are kept; this can be altered with the
2037 history-limit option (see the set-option command above).
2038 The buffer commands are as follows:
2040 choose-buffer [-F format] [-t target-window] [template]
2042 Put a window into buffer choice mode, where a buffer may be cho‐
2043 sen interactively from a list. After a buffer is selected, ‘%%’
2044 is replaced by the buffer name in template and the result exe‐
2045 cuted as a command. If template is not given, "paste-buffer -b
2046 '%%'" is used. For the meaning of the -F flag, see the FORMATS
2047 section. This command works only if at least one client is
2048 attached.
2049 clear-history [-t target-pane]
2051 (alias: clearhist)
2052 Remove and free the history for the specified pane.
2053 delete-buffer [-b buffer-name]
2055 (alias: deleteb)
2056 Delete the buffer named buffer-name, or the most recently added
2057 automatically named buffer if not specified.
2058 list-buffers [-F format]
2060 (alias: lsb)
2061 List the global buffers. For the meaning of the -F flag, see the
2062 FORMATS section.
2063 load-buffer [-b buffer-name] path
2065 (alias: loadb)
2066 Load the contents of the specified paste buffer from path.
2067 paste-buffer [-dpr] [-b buffer-name] [-s separator] [-t target-pane]
2069 (alias: pasteb)
2070 Insert the contents of a paste buffer into the specified pane.
2071 If not specified, paste into the current one. With -d, also
2072 delete the paste buffer. When output, any linefeed (LF) charac‐
2073 ters in the paste buffer are replaced with a separator, by
2074 default carriage return (CR). A custom separator may be speci‐
2075 fied using the -s flag. The -r flag means to do no replacement
2076 (equivalent to a separator of LF). If -p is specified, paste
2077 bracket control codes are inserted around the buffer if the
2078 application has requested bracketed paste mode.
2079 save-buffer [-a] [-b buffer-name] path
2081 (alias: saveb)
2082 Save the contents of the specified paste buffer to path. The -a
2083 option appends to rather than overwriting the file.
2084 set-buffer [-a] [-b buffer-name] [-n new-buffer-name] data
2086 (alias: setb)
2087 Set the contents of the specified buffer to data. The -a option
2088 appends to rather than overwriting the buffer. The -n option
2089 renames the buffer to new-buffer-name.
2090 show-buffer [-b buffer-name]
2092 (alias: showb)
2093 Display the contents of the specified buffer.
2094
2096 Miscellaneous commands are as follows:
2097 clock-mode [-t target-pane]
2099 Display a large clock.
2100 if-shell [-bF] [-t target-pane] shell-command command [command]
2102 (alias: if)
2103 Execute the first command if shell-command returns success or the
2104 second command otherwise. Before being executed, shell-command
2105 is expanded using the rules specified in the FORMATS section,
2106 including those relevant to target-pane. With -b, shell-command
2107 is run in the background.
2108 If -F is given, shell-command is not executed but considered suc‐
2110 cess if neither empty nor zero (after formats are expanded).
2111 lock-server
2113 (alias: lock)
2114 Lock each client individually by running the command specified by
2115 the lock-command option.
2116 run-shell [-b] [-t target-pane] shell-command
2118 (alias: run)
2119 Execute shell-command in the background without creating a win‐
2120 dow. Before being executed, shell-command is expanded using the
2121 rules specified in the FORMATS section. With -b, the command is
2122 run in the background. After it finishes, any output to stdout
2123 is displayed in copy mode (in the pane specified by -t or the
2124 current pane if omitted). If the command doesn't return success,
2125 the exit status is also displayed.
2126 wait-for [-L | -S | -U] channel
2128 (alias: wait)
2129 When used without options, prevents the client from exiting until
2130 woken using wait-for -S with the same channel. When -L is used,
2131 the channel is locked and any clients that try to lock the same
2132 channel are made to wait until the channel is unlocked with
2133 wait-for -U. This command only works from outside tmux.
2134
2136 tmux understands some unofficial extensions to terminfo(5):
2137 Cs, Cr Set the cursor colour. The first takes a single string argument
2139 and is used to set the colour; the second takes no arguments and
2140 restores the default cursor colour. If set, a sequence such as
2141 this may be used to change the cursor colour from inside tmux:
2142 $ printf '\033]12;red\033\\'
2144 Ss, Se Set or reset the cursor style. If set, a sequence such as this
2146 may be used to change the cursor to an underline:
2147 $ printf '\033[4 q'
2149 If Se is not set, Ss with argument 0 will be used to reset the
2151 cursor style instead.
2152 Tc Indicate that the terminal supports the ‘direct colour’ RGB
2154 escape sequence (for example, \e[38;2;255;255;255m).
2155 Ms Store the current buffer in the host terminal's selection (clip‐
2157 board). See the set-clipboard option above and the xterm(1) man
2158 page.
2159
2161 tmux offers a textual interface called control mode. This allows appli‐
2162 cations to communicate with tmux using a simple text-only protocol.
2163 In control mode, a client sends tmux commands or command sequences termi‐
2165 nated by newlines on standard input. Each command will produce one block
2166 of output on standard output. An output block consists of a %begin line
2167 followed by the output (which may be empty). The output block ends with
2168 a %end or %error. %begin and matching %end or %error have two arguments:
2169 an integer time (as seconds from epoch) and command number. For example:
2170 %begin 1363006971 2
2172 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
2173 %end 1363006971 2
2174 In control mode, tmux outputs notifications. A notification will never
2176 occur inside an output block.
2177 The following notifications are defined:
2179 %exit [reason]
2181 The tmux client is exiting immediately, either because it is not
2182 attached to any session or an error occurred. If present, reason
2183 describes why the client exited.
2184 %layout-change window-id window-layout window-visible-layout window-flags
2186 The layout of a window with ID window-id changed. The new layout
2187 is window-layout. The window's visible layout is
2188 window-visible-layout and the window flags are window-flags.
2189 %output pane-id value
2191 A window pane produced output. value escapes non-printable char‐
2192 acters and backslash as octal \xxx.
2193 %session-changed session-id name
2195 The client is now attached to the session with ID session-id,
2196 which is named name.
2197 %session-renamed name
2199 The current session was renamed to name.
2200 %sessions-changed
2202 A session was created or destroyed.
2203 %unlinked-window-add window-id
2205 The window with ID window-id was created but is not linked to the
2206 current session.
2207 %window-add window-id
2209 The window with ID window-id was linked to the current session.
2210 %window-close window-id
2212 The window with ID window-id closed.
2213 %window-renamed window-id name
2215 The window with ID window-id was renamed to name.
2216
2218 ~/.tmux.conf Default tmux configuration file.
2219 /etc/tmux.conf System-wide configuration file.
2220
2222 To create a new tmux session running vi(1):
2223 $ tmux new-session vi
2225 Most commands have a shorter form, known as an alias. For new-session,
2227 this is new:
2228 $ tmux new vi
2230 Alternatively, the shortest unambiguous form of a command is accepted.
2232 If there are several options, they are listed:
2233 $ tmux n
2235 ambiguous command: n, could be: new-session, new-window, next-window
2236 Within an active session, a new window may be created by typing ‘C-b c’
2238 (Ctrl followed by the ‘b’ key followed by the ‘c’ key).
2239 Windows may be navigated with: ‘C-b 0’ (to select window 0), ‘C-b 1’ (to
2241 select window 1), and so on; ‘C-b n’ to select the next window; and ‘C-b
2242 p’ to select the previous window.
2243 A session may be detached using ‘C-b d’ (or by an external event such as
2245 ssh(1) disconnection) and reattached with:
2246 $ tmux attach-session
2248 Typing ‘C-b ?’ lists the current key bindings in the current window; up
2250 and down may be used to navigate the list or ‘q’ to exit from it.
2251 Commands to be run when the tmux server is started may be placed in the
2253 ~/.tmux.conf configuration file. Common examples include:
2254 Changing the default prefix key:
2256 set-option -g prefix C-a
2258 unbind-key C-b
2259 bind-key C-a send-prefix
2260 Turning the status line off, or changing its colour:
2262 set-option -g status off
2264 set-option -g status-style bg=blue
2265 Setting other options, such as the default command, or locking after 30
2267 minutes of inactivity:
2268 set-option -g default-command "exec /bin/ksh"
2270 set-option -g lock-after-time 1800
2271 Creating new key bindings:
2273 bind-key b set-option status
2275 bind-key / command-prompt "split-window 'exec man %%'"
2276 bind-key S command-prompt "new-window -n %1 'ssh %1'"
2277
2279 pty(4)
2280
2282 Nicholas Marriott <nicholas.marriott@gmail.com>
2283BSD June 20, 2019 BSD