1TMATE(1) BSD General Commands Manual TMATE(1)
2
4 tmate — terminal multiplexer
5
7 tmate [-2CluvV] [-c shell-command] [-f file] [-L socket-name]
8 [-S socket-path] [command [flags]]
9
11 tmate is a terminal multiplexer: it enables a number of terminals to be
12 created, accessed, and controlled from a single screen. tmate may be
13 detached from a screen and continue running in the background, then later
14 reattached.
15 When tmate 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 tmate. 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 tmate
26 instances may connect to the same session, and any number of windows may
27 be present in the same session. Once all sessions are killed, tmate
28 exits.
29 Each session is persistent and will survive accidental disconnection
31 (such as ssh(1) connection timeout) or intentional detaching (with the
32 ‘C-b d’ key strokes). tmate may be reattached using:
33 $ tmate attach
35 In tmate, a session is displayed on screen by a client and all sessions
37 are managed by a single server. The server and each client are separate
38 processes which communicate through a socket in /tmp.
39 The options are as follows:
41 -2 Force tmate to assume the terminal supports 256 colours.
43 -C Start in control mode (see the CONTROL MODE section).
45 Given twice (-CC) disables echo.
46 -c shell-command
48 Execute shell-command using the default shell. If neces‐
49 sary, the tmate server will be started to retrieve the
50 default-shell option. This option is for compatibility
51 with sh(1) when tmate is used as a login shell.
52 -f file Specify an alternative configuration file. By default,
54 tmate loads the system configuration file from
55 /etc/tmux.conf, if present, then looks for a user configu‐
56 ration file at ~/.tmux.conf and ~/.tmate.conf.
57 The configuration file is a set of tmate commands which are
59 executed in sequence when the server is first started.
60 tmate loads configuration files once when the server
61 process has started. The source-file command may be used
62 to load a file later.
63 tmate shows any error messages from commands in configura‐
65 tion files in the first session created, and continues to
66 process the rest of the configuration file.
67 -L socket-name
69 tmate stores the server socket in a directory under
70 TMUX_TMPDIR or /tmp if it is unset. The default socket is
71 named default. This option allows a different socket name
72 to be specified, allowing several independent tmate servers
73 to be run. Unlike -S a full path is not necessary: the
74 sockets are all created in the same directory.
75 If the socket is accidentally removed, the SIGUSR1 signal
77 may be sent to the tmate server process to recreate it
78 (note that this will fail if any parent directories are
79 missing).
80 -l Behave as a login shell. This flag currently has no effect
82 and is for compatibility with other shells when using tmate
83 as a login shell.
84 -S socket-path
86 Specify a full alternative path to the server socket. If
87 -S is specified, the default socket directory is not used
88 and any -L flag is ignored.
89 -u tmate attempts to guess if the terminal is likely to sup‐
91 port UTF-8 by checking the first of the LC_ALL, LC_CTYPE
92 and LANG environment variables to be set for the string
93 "UTF-8". This is not always correct: the -u flag explic‐
94 itly informs tmate that UTF-8 is supported.
95 Note that tmate itself always accepts UTF-8; this controls
97 whether it will send UTF-8 characters to the terminal it is
98 running (if not, they are replaced by ‘_’).
99 -v Request verbose logging. This option may be specified mul‐
101 tiple times for increasing verbosity. Log messages will be
102 saved into tmux-client-PID.log and tmux-server-PID.log
103 files in the current directory, where PID is the PID of the
104 server or client process.
105 -V Report the tmate version.
107 command [flags]
109 This specifies one of a set of commands used to control
110 tmate, as described in the following sections. If no com‐
111 mands are specified, the new-session command is assumed.
112
114 tmate may be controlled from an attached client by using a key combina‐
115 tion of a prefix key, ‘C-b’ (Ctrl-b) by default, followed by a command
116 key.
117 The default command key bindings are:
119 C-b Send the prefix key (C-b) through to the application.
121 C-o Rotate the panes in the current window forwards.
122 C-z Suspend the tmate client.
123 ! Break the current pane out of the window.
124 " Split the current pane into two, top and bottom.
125 # List all paste buffers.
126 $ Rename the current session.
127 % Split the current pane into two, left and right.
128 & Kill the current window.
129 ' Prompt for a window index to select.
130 ( Switch the attached client to the previous session.
131 ) Switch the attached client to the next session.
132 , Rename the current window.
133 - Delete the most recently copied buffer of text.
134 . Prompt for an index to move the current window.
135 0 to 9 Select windows 0 to 9.
136 : Enter the tmate command prompt.
137 ; Move to the previously active pane.
138 = Choose which buffer to paste interactively from a list.
139 ? List all key bindings.
140 D Choose a client to detach.
141 L Switch the attached client back to the last session.
142 [ Enter copy mode to copy text or view the history.
143 ] Paste the most recently copied buffer of text.
144 c Create a new window.
145 d Detach the current client.
146 f Prompt to search for text in open windows.
147 i Display some information about the current window.
148 l Move to the previously selected window.
149 n Change to the next window.
150 o Select the next pane in the current window.
151 p Change to the previous window.
152 q Briefly display pane indexes.
153 r Force redraw of the attached client.
154 m Mark the current pane (see select-pane -m).
155 M Clear the marked pane.
156 s Select a new session for the attached client interac‐
157 tively.
158 t Show the time.
159 w Choose the current window interactively.
160 x Kill the current pane.
161 z Toggle zoom state of the current pane.
162 { Swap the current pane with the previous pane.
163 } Swap the current pane with the next pane.
164 ~ Show previous messages from tmate, if any.
165 Page Up Enter copy mode and scroll one page up.
166 Up, Down
167 Left, Right
168 Change to the pane above, below, to the left, or to the
169 right of the current pane.
170 M-1 to M-5 Arrange panes in one of the five preset layouts: even-
171 horizontal, even-vertical, main-horizontal, main-verti‐
172 cal, or tiled.
173 Space Arrange the current window in the next preset layout.
174 M-n Move to the next window with a bell or activity marker.
175 M-o Rotate the panes in the current window backwards.
176 M-p Move to the previous window with a bell or activity
177 marker.
178 C-Up, C-Down
179 C-Left, C-Right
180 Resize the current pane in steps of one cell.
181 M-Up, M-Down
182 M-Left, M-Right
183 Resize the current pane in steps of five cells.
184 Key bindings may be changed with the bind-key and unbind-key commands.
186
188 This section contains a list of the commands supported by tmate. Most
189 commands accept the optional -t (and sometimes -s) argument with one of
190 target-client, target-session target-window, or target-pane. These spec‐
191 ify the client, session, window or pane which a command should affect.
192 target-client is the name of the pty(4) file to which the client is con‐
194 nected, for example either of /dev/ttyp1 or ttyp1 for the client attached
195 to /dev/ttyp1. If no client is specified, tmate attempts to work out the
196 client currently in use; if that fails, an error is reported. Clients
197 may be listed with the list-clients command.
198 target-session is tried as, in order:
200 1. A session ID prefixed with a $.
202 2. An exact name of a session (as listed by the list-sessions
204 command).
205 3. The start of a session name, for example ‘mysess’ would match
207 a session named ‘mysession’.
208 4. An fnmatch(3) pattern which is matched against the session
210 name.
211 If the session name is prefixed with an ‘=’, only an exact match is
213 accepted (so ‘=mysess’ will only match exactly ‘mysess’, not
214 ‘mysession’).
215 If a single session is found, it is used as the target session; multiple
217 matches produce an error. If a session is omitted, the current session
218 is used if available; if no current session is available, the most
219 recently used is chosen.
220 target-window (or src-window or dst-window) specifies a window in the
222 form session:window. session follows the same rules as for
223 target-session, and window is looked for in order as:
224 1. A special token, listed below.
226 2. A window index, for example ‘mysession:1’ is window 1 in ses‐
228 sion ‘mysession’.
229 3. A window ID, such as @1.
231 4. An exact window name, such as ‘mysession:mywindow’.
233 5. The start of a window name, such as ‘mysession:mywin’.
235 6. As an fnmatch(3) pattern matched against the window name.
237 Like sessions, a ‘=’ prefix will do an exact match only. An empty window
239 name specifies the next unused index if appropriate (for example the
240 new-window and link-window commands) otherwise the current window in
241 session is chosen.
242 The following special tokens are available to indicate particular win‐
244 dows. Each has a single-character alternative form.
245 Token Meaning
247 {start} ^ The lowest-numbered window
248 {end} $ The highest-numbered window
249 {last} ! The last (previously current) window
250 {next} + The next window by number
251 {previous} - The previous window by number
252 target-pane (or src-pane or dst-pane) may be a pane ID or takes a similar
254 form to target-window but with the optional addition of a period followed
255 by a pane index or pane ID, for example: ‘mysession:mywindow.1’. If the
256 pane index is omitted, the currently active pane in the specified window
257 is used. The following special tokens are available for the pane index:
258 Token Meaning
260 {last} ! The last (previously active) pane
261 {next} + The next pane by number
262 {previous} - The previous pane by number
263 {top} The top pane
264 {bottom} The bottom pane
265 {left} The leftmost pane
266 {right} The rightmost pane
267 {top-left} The top-left pane
268 {top-right} The top-right pane
269 {bottom-left} The bottom-left pane
270 {bottom-right} The bottom-right pane
271 {up-of} The pane above the active pane
272 {down-of} The pane below the active pane
273 {left-of} The pane to the left of the active pane
274 {right-of} The pane to the right of the active pane
275 The tokens ‘+’ and ‘-’ may be followed by an offset, for example:
277 select-window -t:+2
279 In addition, target-session, target-window or target-pane may consist
281 entirely of the token ‘{mouse}’ (alternative form ‘=’) to specify the
282 most recent mouse event (see the MOUSE SUPPORT section) or ‘{marked}’
283 (alternative form ‘~’) to specify the marked pane (see select-pane -m).
284 Sessions, window and panes are each numbered with a unique ID; session
286 IDs are prefixed with a ‘$’, windows with a ‘@’, and panes with a ‘%’.
287 These are unique and are unchanged for the life of the session, window or
288 pane in the tmate server. The pane ID is passed to the child process of
289 the pane in the TMUX_PANE environment variable. IDs may be displayed
290 using the ‘session_id’, ‘window_id’, or ‘pane_id’ formats (see the
291 FORMATS section) and the display-message, list-sessions, list-windows or
292 list-panes commands.
293 shell-command arguments are sh(1) commands. This may be a single argu‐
295 ment passed to the shell, for example:
296 new-window 'vi /etc/passwd'
298 Will run:
300 /bin/sh -c 'vi /etc/passwd'
302 Additionally, the new-window, new-session, split-window, respawn-window
304 and respawn-pane commands allow shell-command to be given as multiple
305 arguments and executed directly (without ‘sh -c’). This can avoid issues
306 with shell quoting. For example:
307 $ tmate new-window vi /etc/passwd
309 Will run vi(1) directly without invoking the shell.
311 command [arguments] refers to a tmate command, passed with the command
313 and arguments separately, for example:
314 bind-key F1 set-window-option force-width 81
316 Or if using sh(1):
318 $ tmate bind-key F1 set-window-option force-width 81
320 Multiple commands may be specified together as part of a command
322 sequence. Each command should be separated by spaces and a semicolon;
323 commands are executed sequentially from left to right and lines ending
324 with a backslash continue on to the next line, except when escaped by
325 another backslash. A literal semicolon may be included by escaping it
326 with a backslash (for example, when specifying a command sequence to
327 bind-key).
328 Example tmate commands include:
330 refresh-client -t/dev/ttyp2
332 rename-session -tfirst newname
334 set-window-option -t:0 monitor-activity on
336 new-window ; split-window -d
338 bind-key R source-file ~/.tmux.conf \; \
340 display-message "source-file done"
341 Or from sh(1):
343 $ tmate kill-window -t :1
345 $ tmate new-window \; split-window -d
347 $ tmate new-session -d 'vi /etc/passwd' \; split-window -d \; attach
349
351 The tmate server manages clients, sessions, windows and panes. Clients
352 are attached to sessions to interact with them, either when they are cre‐
353 ated with the new-session command, or later with the attach-session com‐
354 mand. Each session has one or more windows linked into it. Windows may
355 be linked to multiple sessions and are made up of one or more panes, each
356 of which contains a pseudo terminal. Commands for creating, linking and
357 otherwise manipulating windows are covered in the WINDOWS AND PANES sec‐
358 tion.
359 The following commands are available to manage clients and sessions:
361 attach-session [-dEr] [-c working-directory] [-t target-session]
363 (alias: attach)
364 If run from outside tmate, create a new client in the current
365 terminal and attach it to target-session. If used from inside,
366 switch the current client. If -d is specified, any other clients
367 attached to the session are detached. -r signifies the client is
368 read-only (only keys bound to the detach-client or switch-client
369 commands have any effect)
370 If no server is started, attach-session will attempt to start it;
372 this will fail unless sessions are created in the configuration
373 file.
374 The target-session rules for attach-session are slightly
376 adjusted: if tmate needs to select the most recently used ses‐
377 sion, it will prefer the most recently used unattached session.
378 -c will set the session working directory (used for new windows)
380 to working-directory.
381 If -E is used, the update-environment option will not be applied.
383 detach-client [-aP] [-s target-session] [-t target-client]
385 (alias: detach)
386 Detach the current client if bound to a key, the client specified
387 with -t, or all clients currently attached to the session speci‐
388 fied by -s. The -a option kills all but the client given with
389 -t. If -P is given, send SIGHUP to the parent process of the
390 client, typically causing it to exit.
391 has-session [-t target-session]
393 (alias: has)
394 Report an error and exit with 1 if the specified session does not
395 exist. If it does exist, exit with 0.
396 kill-server
398 Kill the tmate server and clients and destroy all sessions.
399 kill-session [-aC] [-t target-session]
401 Destroy the given session, closing any windows linked to it and
402 no other sessions, and detaching all clients attached to it. If
403 -a is given, all sessions but the specified one is killed. The
404 -C flag clears alerts (bell, activity, or silence) in all windows
405 linked to the session.
406 list-clients [-F format] [-t target-session]
408 (alias: lsc)
409 List all clients attached to the server. For the meaning of the
410 -F flag, see the FORMATS section. If target-session is speci‐
411 fied, list only clients connected to that session.
412 list-commands
414 (alias: lscm)
415 List the syntax of all commands supported by tmate.
416 list-sessions [-F format]
418 (alias: ls)
419 List all sessions managed by the server. For the meaning of the
420 -F flag, see the FORMATS section.
421 lock-client [-t target-client]
423 (alias: lockc)
424 Lock target-client, see the lock-server command.
425 lock-session [-t target-session]
427 (alias: locks)
428 Lock all clients attached to target-session.
429 new-session [-AdDEP] [-c start-directory] [-F format] [-n window-name]
431 [-s session-name] [-t target-session] [-x width] [-y height]
432 [shell-command]
433 (alias: new)
434 Create a new session with name session-name.
435 The new session is attached to the current terminal unless -d is
437 given. window-name and shell-command are the name of and shell
438 command to execute in the initial window. If -d is used, -x and
439 -y specify the size of the initial window (80 by 24 if not
440 given).
441 If run from a terminal, any termios(4) special characters are
443 saved and used for new windows in the new session.
444 The -A flag makes new-session behave like attach-session if
446 session-name already exists; in this case, -D behaves like -d to
447 attach-session.
448 If -t is given, the new session is grouped with target-session.
450 This means they share the same set of windows - all windows from
451 target-session are linked to the new session, any new windows are
452 linked to both sessions and any windows closed removed from both
453 sessions. The current and previous window and any session
454 options remain independent and either session may be killed with‐
455 out affecting the other. -n and shell-command are invalid if -t
456 is used.
457 The -P option prints information about the new session after it
459 has been created. By default, it uses the format
460 ‘#{session_name}:’ but a different format may be specified with
461 -F.
462 If -E is used, the update-environment option will not be applied.
464 refresh-client [-S] [-t target-client]
466 (alias: refresh)
467 Refresh the current client if bound to a key, or a single client
468 if one is given with -t. If -S is specified, only update the
469 client's status bar.
470 rename-session [-t target-session] new-name
472 (alias: rename)
473 Rename the session to new-name.
474 show-messages [-JT] [-t target-client]
476 (alias: showmsgs)
477 Show client messages or server information. Any messages dis‐
478 played on the status line are saved in a per-client message log,
479 up to a maximum of the limit set by the message-limit server
480 option. With -t, display the log for target-client. -J and -T
481 show debugging information about jobs and terminals.
482 source-file path
484 (alias: source)
485 Execute commands from path.
486 start-server
488 (alias: start)
489 Start the tmate server, if not already running, without creating
490 any sessions.
491 suspend-client [-t target-client]
493 (alias: suspendc)
494 Suspend a client by sending SIGTSTP (tty stop).
495 switch-client [-Elnpr] [-c target-client] [-t target-session] [-T
497 key-table]
498 (alias: switchc)
499 Switch the current session for client target-client to
500 target-session. If -l, -n or -p is used, the client is moved to
501 the last, next or previous session respectively. -r toggles
502 whether a client is read-only (see the attach-session command).
503 If -E is used, update-environment option will not be applied.
505 -T sets the client's key table; the next key from the client will
507 be interpreted from key-table. This may be used to configure
508 multiple prefix keys, or to bind commands to sequences of keys.
509 For example, to make typing ‘abc’ run the list-keys command:
510 bind-key -Ttable2 c list-keys
512 bind-key -Ttable1 b switch-client -Ttable2
513 bind-key -Troot a switch-client -Ttable1
514
516 A tmate window may be in one of several modes. The default permits
517 direct access to the terminal attached to the window. The other is copy
518 mode, which permits a section of a window or its history to be copied to
519 a paste buffer for later insertion into another window. This mode is
520 entered with the copy-mode command, bound to ‘[’ by default. It is also
521 entered when a command that produces output, such as list-keys, is exe‐
522 cuted from a key binding.
523 The keys available depend on whether emacs or vi mode is selected (see
525 the mode-keys option). The following keys are supported as appropriate
526 for the mode:
527 Function vi emacs
529 Append selection A
530 Back to indentation ^ M-m
531 Bottom of history G M-<
532 Clear selection Escape C-g
533 Copy selection Enter M-w
534 Copy to named buffer "
535 Cursor down j Down
536 Cursor left h Left
537 Cursor right l Right
538 Cursor to bottom line L
539 Cursor to middle line M M-r
540 Cursor to top line H M-R
541 Cursor up k Up
542 Delete entire line d C-u
543 Delete/Copy to end of line D C-k
544 End of line $ C-e
545 Go to line : g
546 Half page down C-d M-Down
547 Half page up C-u M-Up
548 Jump again ; ;
549 Jump again in reverse , ,
550 Jump backward F F
551 Jump forward f f
552 Jump to backward T
553 Jump to forward t
554 Next page C-f Page down
555 Next space W
556 Next space, end of word E
557 Next word w
558 Next word end e M-f
559 Other end of selection o
560 Paste buffer p C-y
561 Previous page C-b Page up
562 Previous space B
563 Previous word b M-b
564 Quit mode q Escape
565 Rectangle toggle v R
566 Scroll down C-Down or C-e C-Down
567 Scroll up C-Up or C-y C-Up
568 Search again n n
569 Search again in reverse N N
570 Search backward ? C-r
571 Search forward / C-s
572 Select line V
573 Start of line 0 C-a
574 Start selection Space C-Space
575 Top of history g M->
576 Transpose characters C-t
577 The next and previous word keys use space and the ‘-’, ‘_’ and ‘@’ char‐
579 acters as word delimiters by default, but this can be adjusted by setting
580 the word-separators session option. Next word moves to the start of the
581 next word, next word end to the end of the next word and previous word to
582 the start of the previous word. The three next and previous space keys
583 work similarly but use a space alone as the word separator.
584 The jump commands enable quick movement within a line. For instance,
586 typing ‘f’ followed by ‘/’ will move the cursor to the next ‘/’ character
587 on the current line. A ‘;’ will then jump to the next occurrence.
588 Commands in copy mode may be prefaced by an optional repeat count. With
590 vi key bindings, a prefix is entered using the number keys; with emacs,
591 the Alt (meta) key and a number begins prefix entry. For example, to
592 move the cursor forward by ten words, use ‘M-1 0 M-f’ in emacs mode, and
593 ‘10w’ in vi.
594 Mode key bindings are defined in a set of named tables: vi-edit and
596 emacs-edit for keys used when line editing at the command prompt;
597 vi-choice and emacs-choice for keys used when choosing from lists (such
598 as produced by the choose-window command); and vi-copy and emacs-copy
599 used in copy mode. The tables may be viewed with the list-keys command
600 and keys modified or removed with bind-key and unbind-key. If
601 append-selection, copy-selection, or start-named-buffer are given the -x
602 flag, tmate will not exit copy mode after copying. copy-pipe copies the
603 selection and pipes it to a command. For example the following will bind
604 ‘C-w’ not to exit after copying and ‘C-q’ to copy the selection into /tmp
605 as well as the paste buffer:
606 bind-key -temacs-copy C-w copy-selection -x
608 bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out"
609 The paste buffer key pastes the first line from the top paste buffer on
611 the stack.
612 The synopsis for the copy-mode command is:
614 copy-mode [-Meu] [-t target-pane]
616 Enter copy mode. The -u option scrolls one page up. -M begins a
617 mouse drag (only valid if bound to a mouse key binding, see MOUSE
618 SUPPORT). -e specifies that scrolling to the bottom of the his‐
619 tory (to the visible screen) should exit copy mode. While in
620 copy mode, pressing a key other than those used for scrolling
621 will disable this behaviour. This is intended to allow fast
622 scrolling through a pane's history, for example with:
623 bind PageUp copy-mode -eu
625 Each window displayed by tmate may be split into one or more panes; each
627 pane takes up a certain area of the display and is a separate terminal.
628 A window may be split into panes using the split-window command. Windows
629 may be split horizontally (with the -h flag) or vertically. Panes may be
630 resized with the resize-pane command (bound to ‘C-up’, ‘C-down’ ‘C-left’
631 and ‘C-right’ by default), the current pane may be changed with the
632 select-pane command and the rotate-window and swap-pane commands may be
633 used to swap panes without changing their position. Panes are numbered
634 beginning from zero in the order they are created.
635 A number of preset layouts are available. These may be selected with the
637 select-layout command or cycled with next-layout (bound to ‘Space’ by
638 default); once a layout is chosen, panes within it may be moved and
639 resized as normal.
640 The following layouts are supported:
642 even-horizontal
644 Panes are spread out evenly from left to right across the window.
645 even-vertical
647 Panes are spread evenly from top to bottom.
648 main-horizontal
650 A large (main) pane is shown at the top of the window and the
651 remaining panes are spread from left to right in the leftover
652 space at the bottom. Use the main-pane-height window option to
653 specify the height of the top pane.
654 main-vertical
656 Similar to main-horizontal but the large pane is placed on the
657 left and the others spread from top to bottom along the right.
658 See the main-pane-width window option.
659 tiled Panes are spread out as evenly as possible over the window in
661 both rows and columns.
662 In addition, select-layout may be used to apply a previously used layout
664 - the list-windows command displays the layout of each window in a form
665 suitable for use with select-layout. For example:
666 $ tmate list-windows
668 0: ksh [159x48]
669 layout: bb62,159x48,0,0{79x48,0,0,79x48,80,0}
670 $ tmate select-layout bb62,159x48,0,0{79x48,0,0,79x48,80,0}
671 tmate automatically adjusts the size of the layout for the current window
673 size. Note that a layout cannot be applied to a window with more panes
674 than that from which the layout was originally defined.
675 Commands related to windows and panes are as follows:
677 break-pane [-dP] [-F format] [-s src-pane] [-t dst-window]
679 (alias: breakp)
680 Break src-pane off from its containing window to make it the only
681 pane in dst-window. If -d is given, the new window does not
682 become the current window. The -P option prints information
683 about the new window after it has been created. By default, it
684 uses the format ‘#{session_name}:#{window_index}’ but a different
685 format may be specified with -F.
686 capture-pane [-aepPq] [-b buffer-name] [-E end-line] [-S start-line] [-t
688 target-pane]
689 (alias: capturep)
690 Capture the contents of a pane. If -p is given, the output goes
691 to stdout, otherwise to the buffer specified with -b or a new
692 buffer if omitted. If -a is given, the alternate screen is used,
693 and the history is not accessible. If no alternate screen
694 exists, an error will be returned unless -q is given. If -e is
695 given, the output includes escape sequences for text and back‐
696 ground attributes. -C also escapes non-printable characters as
697 octal \xxx. -J joins wrapped lines and preserves trailing spaces
698 at each line's end. -P captures only any output that the pane
699 has received that is the beginning of an as-yet incomplete escape
700 sequence.
701 -S and -E specify the starting and ending line numbers, zero is
703 the first line of the visible pane and negative numbers are lines
704 in the history. ‘-’ to -S is the start of the history and to -E
705 the end of the visible pane. The default is to capture only the
706 visible contents of the pane.
707 choose-client [-F format] [-t target-window] [template]
709 Put a window into client choice mode, allowing a client to be
710 selected interactively from a list. After a client is chosen,
711 ‘%%’ is replaced by the client pty(4) path in template and the
712 result executed as a command. If template is not given, "detach-
713 client -t '%%'" is used. For the meaning of the -F flag, see the
714 FORMATS section. This command works only if at least one client
715 is attached.
716 choose-session [-F format] [-t target-window] [template]
718 Put a window into session choice mode, where a session may be
719 selected interactively from a list. When one is chosen, ‘%%’ is
720 replaced by the session name in template and the result executed
721 as a command. If template is not given, "switch-client -t '%%'"
722 is used. For the meaning of the -F flag, see the FORMATS sec‐
723 tion. This command works only if at least one client is
724 attached.
725 choose-tree [-suw] [-b session-template] [-c window-template] [-S format]
727 [-W format] [-t target-window]
728 Put a window into tree choice mode, where either sessions or win‐
729 dows may be selected interactively from a list. By default, win‐
730 dows belonging to a session are indented to show their relation‐
731 ship to a session.
732 Note that the choose-window and choose-session commands are wrap‐
734 pers around choose-tree.
735 If -s is given, will show sessions. If -w is given, will show
737 windows.
738 By default, the tree is collapsed and sessions must be expanded
740 to windows with the right arrow key. The -u option will start
741 with all sessions expanded instead.
742 If -b is given, will override the default session command. Note
744 that ‘%%’ can be used and will be replaced with the session name.
745 The default option if not specified is "switch-client -t '%%'".
746 If -c is given, will override the default window command. Like
747 -b, ‘%%’ can be used and will be replaced with the session name
748 and window index. When a window is chosen from the list, the
749 session command is run before the window command.
750 If -S is given will display the specified format instead of the
752 default session format. If -W is given will display the speci‐
753 fied format instead of the default window format. For the mean‐
754 ing of the -s and -w options, see the FORMATS section.
755 This command works only if at least one client is attached.
757 choose-window [-F format] [-t target-window] [template]
759 Put a window into window choice mode, where a window may be cho‐
760 sen interactively from a list. After a window is selected, ‘%%’
761 is replaced by the session name and window index in template and
762 the result executed as a command. If template is not given,
763 "select-window -t '%%'" is used. For the meaning of the -F flag,
764 see the FORMATS section. This command works only if at least one
765 client is attached.
766 display-panes [-t target-client]
768 (alias: displayp)
769 Display a visible indicator of each pane shown by target-client.
770 See the display-panes-time, display-panes-colour, and
771 display-panes-active-colour session options. While the indicator
772 is on screen, a pane may be selected with the ‘0’ to ‘9’ keys.
773 find-window [-CNT] [-F format] [-t target-window] match-string
775 (alias: findw)
776 Search for the fnmatch(3) pattern match-string in window names,
777 titles, and visible content (but not history). The flags control
778 matching behavior: -C matches only visible window contents, -N
779 matches only the window name and -T matches only the window
780 title. The default is -CNT. If only one window is matched,
781 it'll be automatically selected, otherwise a choice list is
782 shown. For the meaning of the -F flag, see the FORMATS section.
783 This command works only if at least one client is attached.
784 join-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane]
786 (alias: joinp)
787 Like split-window, but instead of splitting dst-pane and creating
788 a new pane, split it and move src-pane into the space. This can
789 be used to reverse break-pane. The -b option causes src-pane to
790 be joined to left of or above dst-pane.
791 If -s is omitted and a marked pane is present (see select-pane
793 -m), the marked pane is used rather than the current pane.
794 kill-pane [-a] [-t target-pane]
796 (alias: killp)
797 Destroy the given pane. If no panes remain in the containing
798 window, it is also destroyed. The -a option kills all but the
799 pane given with -t.
800 kill-window [-a] [-t target-window]
802 (alias: killw)
803 Kill the current window or the window at target-window, removing
804 it from any sessions to which it is linked. The -a option kills
805 all but the window given with -t.
806 last-pane [-de] [-t target-window]
808 (alias: lastp)
809 Select the last (previously selected) pane. -e enables or -d
810 disables input to the pane.
811 last-window [-t target-session]
813 (alias: last)
814 Select the last (previously selected) window. If no
815 target-session is specified, select the last window of the cur‐
816 rent session.
817 link-window [-adk] [-s src-window] [-t dst-window]
819 (alias: linkw)
820 Link the window at src-window to the specified dst-window. If
821 dst-window is specified and no such window exists, the src-window
822 is linked there. With -a, the window is moved to the next index
823 up (following windows are moved if necessary). If -k is given
824 and dst-window exists, it is killed, otherwise an error is gener‐
825 ated. If -d is given, the newly linked window is not selected.
826 list-panes [-as] [-F format] [-t target]
828 (alias: lsp)
829 If -a is given, target is ignored and all panes on the server are
830 listed. If -s is given, target is a session (or the current ses‐
831 sion). If neither is given, target is a window (or the current
832 window). For the meaning of the -F flag, see the FORMATS sec‐
833 tion.
834 list-windows [-a] [-F format] [-t target-session]
836 (alias: lsw)
837 If -a is given, list all windows on the server. Otherwise, list
838 windows in the current session or in target-session. For the
839 meaning of the -F flag, see the FORMATS section.
840 move-pane [-bdhv] [-l size | -p percentage] [-s src-pane] [-t dst-pane]
842 (alias: movep)
843 Like join-pane, but src-pane and dst-pane may belong to the same
844 window.
845 move-window [-ardk] [-s src-window] [-t dst-window]
847 (alias: movew)
848 This is similar to link-window, except the window at src-window
849 is moved to dst-window. With -r, all windows in the session are
850 renumbered in sequential order, respecting the base-index option.
851 new-window [-adkP] [-c start-directory] [-F format] [-n window-name] [-t
853 target-window] [shell-command]
854 (alias: neww)
855 Create a new window. With -a, the new window is inserted at the
856 next index up from the specified target-window, moving windows up
857 if necessary, otherwise target-window is the new window location.
858 If -d is given, the session does not make the new window the cur‐
860 rent window. target-window represents the window to be created;
861 if the target already exists an error is shown, unless the -k
862 flag is used, in which case it is destroyed. shell-command is
863 the command to execute. If shell-command is not specified, the
864 value of the default-command option is used. -c specifies the
865 working directory in which the new window is created.
866 When the shell command completes, the window closes. See the
868 remain-on-exit option to change this behaviour.
869 The TERM environment variable must be set to “screen” for all
871 programs running inside tmate. New windows will automatically
872 have “TERM=screen” added to their environment, but care must be
873 taken not to reset this in shell start-up files.
874 The -P option prints information about the new window after it
876 has been created. By default, it uses the format
877 ‘#{session_name}:#{window_index}’ but a different format may be
878 specified with -F.
879 next-layout [-t target-window]
881 (alias: nextl)
882 Move a window to the next layout and rearrange the panes to fit.
883 next-window [-a] [-t target-session]
885 (alias: next)
886 Move to the next window in the session. If -a is used, move to
887 the next window with an alert.
888 pipe-pane [-o] [-t target-pane] [shell-command]
890 (alias: pipep)
891 Pipe any output sent by the program in target-pane to a shell
892 command. A pane may only be piped to one command at a time, any
893 existing pipe is closed before shell-command is executed. The
894 shell-command string may contain the special character sequences
895 supported by the status-left option. If no shell-command is
896 given, the current pipe (if any) is closed.
897 The -o option only opens a new pipe if no previous pipe exists,
899 allowing a pipe to be toggled with a single key, for example:
900 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
902 previous-layout [-t target-window]
904 (alias: prevl)
905 Move to the previous layout in the session.
906 previous-window [-a] [-t target-session]
908 (alias: prev)
909 Move to the previous window in the session. With -a, move to the
910 previous window with an alert.
911 rename-window [-t target-window] new-name
913 (alias: renamew)
914 Rename the current window, or the window at target-window if
915 specified, to new-name.
916 resize-pane [-DLMRUZ] [-t target-pane] [-x width] [-y height]
918 [adjustment]
919 (alias: resizep)
920 Resize a pane, up, down, left or right by adjustment with -U, -D,
921 -L or -R, or to an absolute size with -x or -y. The adjustment
922 is given in lines or cells (the default is 1).
923 With -Z, the active pane is toggled between zoomed (occupying the
925 whole of the window) and unzoomed (its normal position in the
926 layout).
927 -M begins mouse resizing (only valid if bound to a mouse key
929 binding, see MOUSE SUPPORT).
930 respawn-pane [-k] [-t target-pane] [shell-command]
932 (alias: respawnp)
933 Reactivate a pane in which the command has exited (see the
934 remain-on-exit window option). If shell-command is not given,
935 the command used when the pane was created is executed. The pane
936 must be already inactive, unless -k is given, in which case any
937 existing command is killed.
938 respawn-window [-k] [-t target-window] [shell-command]
940 (alias: respawnw)
941 Reactivate a window in which the command has exited (see the
942 remain-on-exit window option). If shell-command is not given,
943 the command used when the window was created is executed. The
944 window must be already inactive, unless -k is given, in which
945 case any existing command is killed.
946 rotate-window [-DU] [-t target-window]
948 (alias: rotatew)
949 Rotate the positions of the panes within a window, either upward
950 (numerically lower) with -U or downward (numerically higher).
951 select-layout [-nop] [-t target-window] [layout-name]
953 (alias: selectl)
954 Choose a specific layout for a window. If layout-name is not
955 given, the last preset layout used (if any) is reapplied. -n and
956 -p are equivalent to the next-layout and previous-layout com‐
957 mands. -o applies the last set layout if possible (undoes the
958 most recent layout change).
959 select-pane [-DdegLlMmRU] [-P style] [-t target-pane]
961 (alias: selectp)
962 Make pane target-pane the active pane in window target-window, or
963 set its style (with -P). If one of -D, -L, -R, or -U is used,
964 respectively the pane below, to the left, to the right, or above
965 the target pane is used. -l is the same as using the last-pane
966 command. -e enables or -d disables input to the pane.
967 -m and -M are used to set and clear the marked pane. There is
969 one marked pane at a time, setting a new marked pane clears the
970 last. The marked pane is the default target for -s to join-pane,
971 swap-pane and swap-window.
972 Each pane has a style: by default the window-style and
974 window-active-style options are used, select-pane -P sets the
975 style for a single pane. For example, to set the pane 1 back‐
976 ground to red:
977 select-pane -t:.1 -P 'bg=red'
979 -g shows the current pane style.
981 select-window [-lnpT] [-t target-window]
983 (alias: selectw)
984 Select the window at target-window. -l, -n and -p are equivalent
985 to the last-window, next-window and previous-window commands. If
986 -T is given and the selected window is already the current win‐
987 dow, the command behaves like last-window.
988 split-window [-bdhvP] [-c start-directory] [-l size | -p percentage] [-t
990 target-pane] [shell-command] [-F format]
991 (alias: splitw)
992 Create a new pane by splitting target-pane: -h does a horizontal
993 split and -v a vertical split; if neither is specified, -v is
994 assumed. The -l and -p options specify the size of the new pane
995 in lines (for vertical split) or in cells (for horizontal split),
996 or as a percentage, respectively. The -b option causes the new
997 pane to be created to the left of or above target-pane. All
998 other options have the same meaning as for the new-window com‐
999 mand.
1000 swap-pane [-dDU] [-s src-pane] [-t dst-pane]
1002 (alias: swapp)
1003 Swap two panes. If -U is used and no source pane is specified
1004 with -s, dst-pane is swapped with the previous pane (before it
1005 numerically); -D swaps with the next pane (after it numerically).
1006 -d instructs tmate not to change the active pane.
1007 If -s is omitted and a marked pane is present (see select-pane
1009 -m), the marked pane is used rather than the current pane.
1010 swap-window [-d] [-s src-window] [-t dst-window]
1012 (alias: swapw)
1013 This is similar to link-window, except the source and destination
1014 windows are swapped. It is an error if no window exists at
1015 src-window.
1016 Like swap-pane, if -s is omitted and a marked pane is present
1018 (see select-pane -m), the window containing the marked pane is
1019 used rather than the current window.
1020 unlink-window [-k] [-t target-window]
1022 (alias: unlinkw)
1023 Unlink target-window. Unless -k is given, a window may be
1024 unlinked only if it is linked to multiple sessions - windows may
1025 not be linked to no sessions; if -k is specified and the window
1026 is linked to only one session, it is unlinked and destroyed.
1027
1029 tmate allows a command to be bound to most keys, with or without a prefix
1030 key. When specifying keys, most represent themselves (for example ‘A’ to
1031 ‘Z’). Ctrl keys may be prefixed with ‘C-’ or ‘^’, and Alt (meta) with
1032 ‘M-’. In addition, the following special key names are accepted: Up,
1033 Down, Left, Right, BSpace, BTab, DC (Delete), End, Enter, Escape, F1 to
1034 F12, Home, IC (Insert), NPage/PageDown/PgDn, PPage/PageUp/PgUp, Space,
1035 and Tab. Note that to bind the ‘"’ or ‘'’ keys, quotation marks are nec‐
1036 essary, for example:
1037 bind-key '"' split-window
1039 bind-key "'" new-window
1040 Commands related to key bindings are as follows:
1042 bind-key [-cnr] [-t mode-table] [-T key-table] key command [arguments]
1044 (alias: bind)
1045 Bind key key to command. Keys are bound in a key table. By
1046 default (without -T), the key is bound in the prefix key table.
1047 This table is used for keys pressed after the prefix key (for
1048 example, by default ‘c’ is bound to new-window in the prefix ta‐
1049 ble, so ‘C-b c’ creates a new window). The root table is used
1050 for keys pressed without the prefix key: binding ‘c’ to
1051 new-window in the root table (not recommended) means a plain ‘c’
1052 will create a new window. -n is an alias for -T root. Keys may
1053 also be bound in custom key tables and the switch-client -T com‐
1054 mand used to switch to them from a key binding. The -r flag
1055 indicates this key may repeat, see the repeat-time option.
1056 If -t is present, key is bound in mode-table: the binding for
1058 command mode with -c or for normal mode without. See the WINDOWS
1059 AND PANES section and the list-keys command for information on
1060 mode key bindings.
1061 To view the default bindings and possible commands, see the
1063 list-keys command.
1064 list-keys [-t mode-table] [-T key-table]
1066 (alias: lsk)
1067 List all key bindings. Without -T all key tables are printed.
1068 With -T only key-table.
1069 With -t, the key bindings in mode-table are listed; this may be
1071 one of: vi-edit, emacs-edit, vi-choice, emacs-choice, vi-copy or
1072 emacs-copy.
1073 send-keys [-lMR] [-t target-pane] key ...
1075 (alias: send)
1076 Send a key or keys to a window. Each argument key is the name of
1077 the key (such as ‘C-a’ or ‘npage’ ) to send; if the string is not
1078 recognised as a key, it is sent as a series of characters. The
1079 -l flag disables key name lookup and sends the keys literally.
1080 All arguments are sent sequentially from first to last. The -R
1081 flag causes the terminal state to be reset.
1082 -M passes through a mouse event (only valid if bound to a mouse
1084 key binding, see MOUSE SUPPORT).
1085 send-prefix [-2] [-t target-pane]
1087 Send the prefix key, or with -2 the secondary prefix key, to a
1088 window as if it was pressed.
1089 unbind-key [-acn] [-t mode-table] [-T key-table] key
1091 (alias: unbind)
1092 Unbind the command bound to key. -c, -n, -T and -t are the same
1093 as for bind-key. If -a is present, all key bindings are removed.
1094
1096 The appearance and behaviour of tmate may be modified by changing the
1097 value of various options. There are three types of option: server
1098 options, session options and window options.
1099 The tmate server has a set of global options which do not apply to any
1101 particular window or session. These are altered with the set-option -s
1102 command, or displayed with the show-options -s command.
1103 In addition, each individual session may have a set of session options,
1105 and there is a separate set of global session options. Sessions which do
1106 not have a particular option configured inherit the value from the global
1107 session options. Session options are set or unset with the set-option
1108 command and may be listed with the show-options command. The available
1109 server and session options are listed under the set-option command.
1110 Similarly, a set of window options is attached to each window, and there
1112 is a set of global window options from which any unset options are inher‐
1113 ited. Window options are altered with the set-window-option command and
1114 can be listed with the show-window-options command. All window options
1115 are documented with the set-window-option command.
1116 tmate also supports user options which are prefixed with a ‘@’. User
1118 options may have any name, so long as they are prefixed with ‘@’, and be
1119 set to any string. For example:
1120 $ tmate setw -q @foo "abc123"
1122 $ tmate showw -v @foo
1123 abc123
1124 Commands which set options are as follows:
1126 set-option [-agoqsuw] [-t target-session | target-window] option value
1128 (alias: set)
1129 Set a window option with -w (equivalent to the set-window-option
1130 command), a server option with -s, otherwise a session option.
1131 If -g is given, the global session or window option is set. The
1132 -u flag unsets an option, so a session inherits the option from
1133 the global options (or with -g, restores a global option to the
1134 default).
1135 The -o flag prevents setting an option that is already set and
1137 the -q flag suppresses errors about unknown or ambiguous options.
1138 With -a, and if the option expects a string or a style, value is
1140 appended to the existing setting. For example:
1141 set -g status-left "foo"
1143 set -ag status-left "bar"
1144 Will result in ‘foobar’. And:
1146 set -g status-style "bg=red"
1148 set -ag status-style "fg=blue"
1149 Will result in a red background and blue foreground. Without -a,
1151 the result would be the default background and a blue foreground.
1152 Available window options are listed under set-window-option.
1154 value depends on the option and may be a number, a string, or a
1156 flag (on, off, or omitted to toggle).
1157 Available server options are:
1159 buffer-limit number
1161 Set the number of buffers; as new buffers are added to
1162 the top of the stack, old ones are removed from the bot‐
1163 tom if necessary to maintain this maximum length.
1164 default-terminal terminal
1166 Set the default terminal for new windows created in this
1167 session - the default value of the TERM environment vari‐
1168 able. For tmate to work correctly, this must be set to
1169 ‘screen’, ‘tmux’, ‘tmate’ or a derivative of them.
1170 escape-time time
1172 Set the time in milliseconds for which tmate waits after
1173 an escape is input to determine if it is part of a func‐
1174 tion or meta key sequences. The default is 500 millisec‐
1175 onds.
1176 exit-unattached [on | off]
1178 If enabled, the server will exit when there are no
1179 attached clients.
1180 focus-events [on | off]
1182 When enabled, focus events are requested from the termi‐
1183 nal if supported and passed through to applications run‐
1184 ning in tmate. Attached clients should be detached and
1185 attached again after changing this option.
1186 history-file path
1188 If not empty, a file to which tmate will write command
1189 prompt history on exit and load it from on start.
1190 message-limit number
1192 Set the number of error or information messages to save
1193 in the message log for each client. The default is 100.
1194 set-clipboard [on | off]
1196 Attempt to set the terminal clipboard content using the
1197 \e]52;...\007 xterm(1) escape sequences. This option is
1198 on by default if there is an Ms entry in the terminfo(5)
1199 description for the client terminal. Note that this fea‐
1200 ture needs to be enabled in xterm(1) by setting the
1201 resource:
1202 disallowedWindowOps: 20,21,SetXprop
1204 Or changing this property from the xterm(1) interactive
1206 menu when required.
1207 terminal-overrides string
1209 Contains a list of entries which override terminal
1210 descriptions read using terminfo(5). string is a comma-
1211 separated list of items each a colon-separated string
1212 made up of a terminal type pattern (matched using
1213 fnmatch(3)) and a set of name=value entries.
1214 For example, to set the ‘clear’ terminfo(5) entry to
1216 ‘\e[H\e[2J’ for all terminal types and the ‘dch1’ entry
1217 to ‘\e[P’ for the ‘rxvt’ terminal type, the option could
1218 be set to the string:
1219 "*:clear=\e[H\e[2J,rxvt:dch1=\e[P"
1221 The terminal entry value is passed through strunvis(3)
1223 before interpretation. The default value forcibly cor‐
1224 rects the ‘colors’ entry for terminals which support 256
1225 colours:
1226 "*256col*:colors=256,xterm*:XT"
1228 Available session options are:
1230 assume-paste-time milliseconds
1232 If keys are entered faster than one in milliseconds, they
1233 are assumed to have been pasted rather than typed and
1234 tmate key bindings are not processed. The default is one
1235 millisecond and zero disables.
1236 base-index index
1238 Set the base index from which an unused index should be
1239 searched when a new window is created. The default is
1240 zero.
1241 bell-action [any | none | current | other]
1243 Set action on window bell. any means a bell in any win‐
1244 dow linked to a session causes a bell in the current win‐
1245 dow of that session, none means all bells are ignored,
1246 current means only bells in windows other than the cur‐
1247 rent window are ignored and other means bells in the cur‐
1248 rent window are ignored but not those in other windows.
1249 bell-on-alert [on | off]
1251 If on, ring the terminal bell when an alert occurs.
1252 default-command shell-command
1254 Set the command used for new windows (if not specified
1255 when the window is created) to shell-command, which may
1256 be any sh(1) command. The default is an empty string,
1257 which instructs tmate to create a login shell using the
1258 value of the default-shell option.
1259 default-shell path
1261 Specify the default shell. This is used as the login
1262 shell for new windows when the default-command option is
1263 set to empty, and must be the full path of the exe‐
1264 cutable. When started tmate tries to set a default value
1265 from the first suitable of the SHELL environment vari‐
1266 able, the shell returned by getpwuid(3), or /bin/sh.
1267 This option should be configured when tmate is used as a
1268 login shell.
1269 destroy-unattached [on | off]
1271 If enabled and the session is no longer attached to any
1272 clients, it is destroyed.
1273 detach-on-destroy [on | off]
1275 If on (the default), the client is detached when the ses‐
1276 sion it is attached to is destroyed. If off, the client
1277 is switched to the most recently active of the remaining
1278 sessions.
1279 display-panes-active-colour colour
1281 Set the colour used by the display-panes command to show
1282 the indicator for the active pane.
1283 display-panes-colour colour
1285 Set the colour used by the display-panes command to show
1286 the indicators for inactive panes.
1287 display-panes-time time
1289 Set the time in milliseconds for which the indicators
1290 shown by the display-panes command appear.
1291 display-time time
1293 Set the amount of time for which status line messages and
1294 other on-screen indicators are displayed. If set to 0,
1295 messages and indicators are displayed until a key is
1296 pressed. time is in milliseconds.
1297 history-limit lines
1299 Set the maximum number of lines held in window history.
1300 This setting applies only to new windows - existing win‐
1301 dow histories are not resized and retain the limit at the
1302 point they were created.
1303 key-table key-table
1305 Set the default key table to key-table instead of root.
1306 lock-after-time number
1308 Lock the session (like the lock-session command) after
1309 number seconds of inactivity. The default is not to lock
1310 (set to 0).
1311 lock-command shell-command
1313 Command to run when locking each client. The default is
1314 to run lock(1) with -np.
1315 message-command-style style
1317 Set status line message command style, where style is a
1318 comma-separated list of characteristics to be specified.
1319 These may be ‘bg=colour’ to set the background colour,
1321 ‘fg=colour’ to set the foreground colour, and a list of
1322 attributes as specified below.
1323 The colour is one of: black, red, green, yellow, blue,
1325 magenta, cyan, white, aixterm bright variants (if sup‐
1326 ported: brightred, brightgreen, and so on), colour0 to
1327 colour255 from the 256-colour set, default, or a hexadec‐
1328 imal RGB string such as ‘#ffffff’, which chooses the
1329 closest match from the default 256-colour set.
1330 The attributes is either none or a comma-delimited list
1332 of one or more of: bright (or bold), dim, underscore,
1333 blink, reverse, hidden, or italics, to turn an attribute
1334 on, or an attribute prefixed with ‘no’ to turn one off.
1335 Examples are:
1337 fg=yellow,bold,underscore,blink
1339 bg=black,fg=default,noreverse
1340 With the -a flag to the set-option command the new style
1342 is added otherwise the existing style is replaced.
1343 message-style style
1345 Set status line message style. For how to specify style,
1346 see the message-command-style option.
1347 mouse [on | off]
1349 If on, tmate captures the mouse and allows mouse events
1350 to be bound as key bindings. See the MOUSE SUPPORT sec‐
1351 tion for details.
1352 prefix key
1354 Set the key accepted as a prefix key. In addition to the
1355 standard keys described under KEY BINDINGS, prefix can be
1356 set to the special key ‘None’ to set no prefix.
1357 prefix2 key
1359 Set a secondary key accepted as a prefix key. Like
1360 prefix, prefix2 can be set to ‘None’.
1361 renumber-windows [on | off]
1363 If on, when a window is closed in a session, automati‐
1364 cally renumber the other windows in numerical order.
1365 This respects the base-index option if it has been set.
1366 If off, do not renumber the windows.
1367 repeat-time time
1369 Allow multiple commands to be entered without pressing
1370 the prefix-key again in the specified time milliseconds
1371 (the default is 500). Whether a key repeats may be set
1372 when it is bound using the -r flag to bind-key. Repeat
1373 is enabled for the default keys bound to the resize-pane
1374 command.
1375 set-remain-on-exit [on | off]
1377 Set the remain-on-exit window option for any windows
1378 first created in this session. When this option is true,
1379 windows in which the running program has exited do not
1380 close, instead remaining open but inactivate. Use the
1381 respawn-window command to reactivate such a window, or
1382 the kill-window command to destroy it.
1383 set-titles [on | off]
1385 Attempt to set the client terminal title using the tsl
1386 and fsl terminfo(5) entries if they exist. tmate auto‐
1387 matically sets these to the \e]0;...\007 sequence if the
1388 terminal appears to be xterm(1). This option is off by
1389 default.
1390 set-titles-string string
1392 String used to set the window title if set-titles is on.
1393 Formats are expanded, see the FORMATS section.
1394 status [on | off]
1396 Show or hide the status line.
1397 status-interval interval
1399 Update the status bar every interval seconds. By
1400 default, updates will occur every 15 seconds. A setting
1401 of zero disables redrawing at interval.
1402 status-justify [left | centre | right]
1404 Set the position of the window list component of the sta‐
1405 tus line: left, centre or right justified.
1406 status-keys [vi | emacs]
1408 Use vi or emacs-style key bindings in the status line,
1409 for example at the command prompt. The default is emacs,
1410 unless the VISUAL or EDITOR environment variables are set
1411 and contain the string ‘vi’.
1412 status-left string
1414 Display string (by default the session name) to the left
1415 of the status bar. string will be passed through
1416 strftime(3) and formats (see FORMATS) will be expanded.
1417 It may also contain any of the following special charac‐
1418 ter sequences:
1419 Character pair Replaced with
1421 #[attributes] Colour or attribute change
1422 ## A literal ‘#’
1423 For details on how the names and titles can be set see
1425 the NAMES AND TITLES section. For a list of allowed
1426 attributes see the message-command-style option.
1427 Examples are:
1429 #(sysctl vm.loadavg)
1431 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
1432 The default is ‘[#S] ’.
1434 status-left-length length
1436 Set the maximum length of the left component of the sta‐
1437 tus bar. The default is 10.
1438 status-left-style style
1440 Set the style of the left part of the status line. For
1441 how to specify style, see the message-command-style
1442 option.
1443 status-position [top | bottom]
1445 Set the position of the status line.
1446 status-right string
1448 Display string to the right of the status bar. By
1449 default, the current window title in double quotes, the
1450 date and the time are shown. As with status-left, string
1451 will be passed to strftime(3) and character pairs are
1452 replaced.
1453 status-right-length length
1455 Set the maximum length of the right component of the sta‐
1456 tus bar. The default is 40.
1457 status-right-style style
1459 Set the style of the right part of the status line. For
1460 how to specify style, see the message-command-style
1461 option.
1462 status-style style
1464 Set status line style. For how to specify style, see the
1465 message-command-style option.
1466 update-environment variables
1468 Set a space-separated string containing a list of envi‐
1469 ronment variables to be copied into the session environ‐
1470 ment when a new session is created or an existing session
1471 is attached. Any variables that do not exist in the
1472 source environment are set to be removed from the session
1473 environment (as if -r was given to the set-environment
1474 command). The default is "DISPLAY SSH_ASKPASS
1475 SSH_AUTH_SOCK SSH_AGENT_PID SSH_CONNECTION WINDOWID XAU‐
1476 THORITY".
1477 visual-activity [on | off]
1479 If on, display a status line message when activity occurs
1480 in a window for which the monitor-activity window option
1481 is enabled.
1482 visual-bell [on | off]
1484 If this option is on, a message is shown on a bell
1485 instead of it being passed through to the terminal (which
1486 normally makes a sound). Also see the bell-action
1487 option.
1488 visual-silence [on | off]
1490 If monitor-silence is enabled, prints a message after the
1491 interval has expired on a given window.
1492 word-separators string
1494 Sets the session's conception of what characters are con‐
1495 sidered word separators, for the purposes of the next and
1496 previous word commands in copy mode. The default is
1497 ‘ -_@’.
1498 set-window-option [-agoqu] [-t target-window] option value
1500 (alias: setw)
1501 Set a window option. The -a, -g, -o, -q and -u flags work simi‐
1502 larly to the set-option command.
1503 Supported window options are:
1505 aggressive-resize [on | off]
1507 Aggressively resize the chosen window. This means that
1508 tmate will resize the window to the size of the smallest
1509 session for which it is the current window, rather than
1510 the smallest session to which it is attached. The window
1511 may resize when the current window is changed on another
1512 sessions; this option is good for full-screen programs
1513 which support SIGWINCH and poor for interactive programs
1514 such as shells.
1515 allow-rename [on | off]
1517 Allow programs to change the window name using a terminal
1518 escape sequence (\ek...\e\\). The default is on.
1519 alternate-screen [on | off]
1521 This option configures whether programs running inside
1522 tmate may use the terminal alternate screen feature,
1523 which allows the smcup and rmcup terminfo(5) capabili‐
1524 ties. The alternate screen feature preserves the con‐
1525 tents of the window when an interactive application
1526 starts and restores it on exit, so that any output visi‐
1527 ble before the application starts reappears unchanged
1528 after it exits. The default is on.
1529 automatic-rename [on | off]
1531 Control automatic window renaming. When this setting is
1532 enabled, tmate will rename the window automatically using
1533 the format specified by automatic-rename-format. This
1534 flag is automatically disabled for an individual window
1535 when a name is specified at creation with new-window or
1536 new-session, or later with rename-window, or with a ter‐
1537 minal escape sequence. It may be switched off globally
1538 with:
1539 set-window-option -g automatic-rename off
1541 automatic-rename-format format
1543 The format (see FORMATS) used when the automatic-rename
1544 option is enabled.
1545 clock-mode-colour colour
1547 Set clock colour.
1548 clock-mode-style [12 | 24]
1550 Set clock hour format.
1551 force-height height
1553 force-width width
1554 Prevent tmate from resizing a window to greater than
1555 width or height. A value of zero restores the default
1556 unlimited setting.
1557 main-pane-height height
1559 main-pane-width width
1560 Set the width or height of the main (left or top) pane in
1561 the main-horizontal or main-vertical layouts.
1562 mode-keys [vi | emacs]
1564 Use vi or emacs-style key bindings in copy and choice
1565 modes. As with the status-keys option, the default is
1566 emacs, unless VISUAL or EDITOR contains ‘vi’.
1567 mode-style style
1569 Set window modes style. For how to specify style, see
1570 the message-command-style option.
1571 monitor-activity [on | off]
1573 Monitor for activity in the window. Windows with activ‐
1574 ity are highlighted in the status line.
1575 monitor-silence [interval]
1577 Monitor for silence (no activity) in the window within
1578 interval seconds. Windows that have been silent for the
1579 interval are highlighted in the status line. An interval
1580 of zero disables the monitoring.
1581 other-pane-height height
1583 Set the height of the other panes (not the main pane) in
1584 the main-horizontal layout. If this option is set to 0
1585 (the default), it will have no effect. If both the
1586 main-pane-height and other-pane-height options are set,
1587 the main pane will grow taller to make the other panes
1588 the specified height, but will never shrink to do so.
1589 other-pane-width width
1591 Like other-pane-height, but set the width of other panes
1592 in the main-vertical layout.
1593 pane-active-border-style style
1595 Set the pane border style for the currently active pane.
1596 For how to specify style, see the message-command-style
1597 option. Attributes are ignored.
1598 pane-base-index index
1600 Like base-index, but set the starting index for pane num‐
1601 bers.
1602 pane-border-style style
1604 Set the pane border style for panes aside from the active
1605 pane. For how to specify style, see the
1606 message-command-style option. Attributes are ignored.
1607 remain-on-exit [on | off]
1609 A window with this flag set is not destroyed when the
1610 program running in it exits. The window may be reacti‐
1611 vated with the respawn-window command.
1612 synchronize-panes [on | off]
1614 Duplicate input to any pane to all other panes in the
1615 same window (only for panes that are not in any special
1616 mode).
1617 window-active-style style
1619 Set the style for the window's active pane. For how to
1620 specify style, see the message-command-style option.
1621 window-status-activity-style style
1623 Set status line style for windows with an activity alert.
1624 For how to specify style, see the message-command-style
1625 option.
1626 window-status-bell-style style
1628 Set status line style for windows with a bell alert. For
1629 how to specify style, see the message-command-style
1630 option.
1631 window-status-current-format string
1633 Like window-status-format, but is the format used when
1634 the window is the current window.
1635 window-status-current-style style
1637 Set status line style for the currently active window.
1638 For how to specify style, see the message-command-style
1639 option.
1640 window-status-format string
1642 Set the format in which the window is displayed in the
1643 status line window list. See the status-left option for
1644 details of special character sequences available. The
1645 default is ‘#I:#W#F’.
1646 window-status-last-style style
1648 Set status line style for the last active window. For
1649 how to specify style, see the message-command-style
1650 option.
1651 window-status-separator string
1653 Sets the separator drawn between windows in the status
1654 line. The default is a single space character.
1655 window-status-style style
1657 Set status line style for a single window. For how to
1658 specify style, see the message-command-style option.
1659 window-style style
1661 Set the default window style. For how to specify style,
1662 see the message-command-style option.
1663 xterm-keys [on | off]
1665 If this option is set, tmate will generate xterm(1)
1666 -style function key sequences; these have a number
1667 included to indicate modifiers such as Shift, Alt or
1668 Ctrl. The default is off.
1669 wrap-search [on | off]
1671 If this option is set, searches will wrap around the end
1672 of the pane contents. The default is on.
1673 show-options [-gqsvw] [-t target-session | target-window] [option]
1675 (alias: show)
1676 Show the window options (or a single window option if given) with
1677 -w (equivalent to show-window-options), the server options with
1678 -s, otherwise the session options for target session. Global
1679 session or window options are listed if -g is used. -v shows
1680 only the option value, not the name. If -q is set, no error will
1681 be returned if option is unset.
1682 show-window-options [-gv] [-t target-window] [option]
1684 (alias: showw)
1685 List the window options or a single option for target-window, or
1686 the global window options if -g is used. -v shows only the
1687 option value, not the name.
1688
1690 tmate allows commands to run on various triggers, called hooks. Each
1691 hook has a name. The following hooks are available:
1692 alert-activity Run when a window has activity. See monitor-activity.
1694 alert-bell Run when a window has received a bell.
1696 alert-silence Run when a window has been silent. See
1698 monitor-silence.
1699 client-attached Run when a client is attached.
1701 client-detached Run when a client is detached
1703 client-resized Run when a client is resized.
1705 pane-died Run when the program running in a pane exits, but
1707 remain-on-exit is on so the pane has not closed.
1708 pane-exited Run when the program running in a pane exits.
1710 Hooks are managed with these commands:
1712 set-hook [-g] [-t target-session] hook-name command
1714 Sets hook hook-name to command. If -g is given, hook-name is
1715 added to the global list of hooks, otherwise it is added to the
1716 session hooks (for target-session with -t). Like options, ses‐
1717 sion hooks inherit from the global ones.
1718 show-hooks [-g] [-t target-session]
1720 Shows the global list of hooks with -g, otherwise the session
1721 hooks.
1722
1724 If the mouse option is on (the default is off), tmate allows mouse events
1725 to be bound as keys. The name of each key is made up of a mouse event
1726 (such as ‘MouseUp1’) and a location suffix (one of ‘Pane’ for the con‐
1727 tents of a pane, ‘Border’ for a pane border or ‘Status’ for the status
1728 line). The following mouse events are available:
1729 MouseDown1 MouseUp1 MouseDrag1 MouseDragEnd1
1731 MouseDown2 MouseUp2 MouseDrag2 MouseDragEnd2
1732 MouseDown3 MouseUp3 MouseDrag3 MouseDragEnd3
1733 WheelUp WheelDown
1734 Each should be suffixed with a location, for example ‘MouseDown1Status’.
1736 The special token ‘{mouse}’ or ‘=’ may be used as target-window or
1738 target-pane in commands bound to mouse key bindings. It resolves to the
1739 window or pane over which the mouse event took place (for example, the
1740 window in the status line over which button 1 was released for a
1741 ‘MouseUp1Status’ binding, or the pane over which the wheel was scrolled
1742 for a ‘WheelDownPane’ binding).
1743 The send-keys -M flag may be used to forward a mouse event to a pane.
1745 The default key bindings allow the mouse to be used to select and resize
1747 panes, to copy text and to change window using the status line. These
1748 take effect if the mouse option is turned on.
1749
1751 Certain commands accept the -F flag with a format argument. This is a
1752 string which controls the output format of the command. Replacement
1753 variables are enclosed in ‘#{’ and ‘}’, for example ‘#{session_name}’.
1754 The possible variables are listed in the table below, or the name of a
1755 tmate option may be used for an option's value. Some variables have a
1756 shorter alias such as ‘#S’, and ‘##’ is replaced by a single ‘#’.
1757 Conditionals are available by prefixing with ‘?’ and separating two
1759 alternatives with a comma; if the specified variable exists and is not
1760 zero, the first alternative is chosen, otherwise the second is used. For
1761 example ‘#{?session_attached,attached,not attached}’ will include the
1762 string ‘attached’ if the session is attached and the string ‘not
1763 attached’ if it is unattached, or ‘#{?automatic-rename,yes,no}’ will
1764 include ‘yes’ if automatic-rename is enabled, or ‘no’ if not.
1765 A limit may be placed on the length of the resultant string by prefixing
1767 it by an ‘=’, a number and a colon. Positive numbers count from the
1768 start of the string and negative from the end, so ‘#{=5:pane_title}’ will
1769 include at most the first 5 characters of the pane title, or
1770 ‘#{=-5:pane_title}’ the last 5 characters. Prefixing a time variable
1771 with ‘t:’ will convert it to a string, so if ‘#{window_activity}’ gives
1772 ‘1445765102’, ‘#{t:window_activity}’ gives ‘Sun Oct 25 09:25:02 2015’.
1773 The ‘b:’ and ‘d:’ prefixes are basename(3) and dirname(3) of the variable
1774 respectively. A prefix of the form ‘s/foo/bar/:’ will substitute ‘foo’
1775 with ‘bar’ throughout.
1776 In addition, the first line of a shell command's output may be inserted
1778 using ‘#()’. For example, ‘#(uptime)’ will insert the system's uptime.
1779 When constructing formats, tmate does not wait for ‘#()’ commands to fin‐
1780 ish; instead, the previous result from running the same command is used,
1781 or a placeholder if the command has not been run before. Commands are
1782 executed with the tmate global environment set (see the ENVIRONMENT sec‐
1783 tion).
1784 The following variables are available, where appropriate:
1786 Variable name Alias Replaced with
1788 alternate_on If pane is in alternate screen
1789 alternate_saved_x Saved cursor X in alternate screen
1790 alternate_saved_y Saved cursor Y in alternate screen
1791 buffer_sample Sample of start of buffer
1792 buffer_size Size of the specified buffer in bytes
1793 client_activity Integer time client last had activity
1794 client_created Integer time client created
1795 client_control_mode 1 if client is in control mode
1796 client_height Height of client
1797 client_key_table Current key table
1798 client_last_session Name of the client's last session
1799 client_pid PID of client process
1800 client_prefix 1 if prefix key has been pressed
1801 client_readonly 1 if client is readonly
1802 client_session Name of the client's session
1803 client_termname Terminal name of client
1804 client_tty Pseudo terminal of client
1805 client_utf8 1 if client supports utf8
1806 client_width Width of client
1807 command_name Name of command in use, if any
1808 cursor_flag Pane cursor flag
1809 cursor_x Cursor X position in pane
1810 cursor_y Cursor Y position in pane
1811 history_bytes Number of bytes in window history
1812 history_limit Maximum window history lines
1813 history_size Size of history in bytes
1814 host #H Hostname of local host
1815 host_short #h Hostname of local host (no domain name)
1816 insert_flag Pane insert flag
1817 keypad_cursor_flag Pane keypad cursor flag
1818 keypad_flag Pane keypad flag
1819 line Line number in the list
1820 mouse_any_flag Pane mouse any flag
1821 mouse_button_flag Pane mouse button flag
1822 mouse_standard_flag Pane mouse standard flag
1823 pane_active 1 if active pane
1824 pane_bottom Bottom of pane
1825 pane_current_command Current command if available
1826 pane_current_path Current path if available
1827 pane_dead 1 if pane is dead
1828 pane_dead_status Exit status of process in dead pane
1829 pane_height Height of pane
1830 pane_id #D Unique pane ID
1831 pane_in_mode If pane is in a mode
1832 pane_input_off If input to pane is disabled
1833 pane_index #P Index of pane
1834 pane_left Left of pane
1835 pane_pid PID of first process in pane
1836 pane_right Right of pane
1837 pane_start_command Command pane started with
1838 pane_synchronized If pane is synchronized
1839 pane_tabs Pane tab positions
1840 pane_title #T Title of pane
1841 pane_top Top of pane
1842 pane_tty Pseudo terminal of pane
1843 pane_width Width of pane
1844 pid Server PID
1845 scroll_region_lower Bottom of scroll region in pane
1846 scroll_region_upper Top of scroll region in pane
1847 scroll_position Scroll position in copy mode
1848 session_alerts List of window indexes with alerts
1849 session_attached Number of clients session is attached to
1850 session_activity Integer time of session last activity
1851 session_created Integer time session created
1852 session_last_attached Integer time session last attached
1853 session_group Number of session group
1854 session_grouped 1 if session in a group
1855 session_height Height of session
1856 session_id Unique session ID
1857 session_many_attached 1 if multiple clients attached
1858 session_name #S Name of session
1859 session_width Width of session
1860 session_windows Number of windows in session
1861 socket_path Server socket path
1862 start_time Server start time
1863 window_activity Integer time of window last activity
1864 window_active 1 if window active
1865 window_bell_flag 1 if window has bell
1866 window_find_matches Matched data from the find-window
1867 window_flags #F Window flags
1868 window_height Height of window
1869 window_id Unique window ID
1870 window_index #I Index of window
1871 window_last_flag 1 if window is the last used
1872 window_layout Window layout description, ignoring
1873 zoomed window panes
1874 window_linked 1 if window is linked across sessions
1875 window_name #W Name of window
1876 window_panes Number of panes in window
1877 window_silence_flag 1 if window has silence alert
1878 window_visible_layout Window layout description, respecting
1879 zoomed window panes
1880 window_width Width of window
1881 window_zoomed_flag 1 if window is zoomed
1882 wrap_flag Pane wrap flag
1883
1885 tmate distinguishes between names and titles. Windows and sessions have
1886 names, which may be used to specify them in targets and are displayed in
1887 the status line and various lists: the name is the tmate identifier for a
1888 window or session. Only panes have titles. A pane's title is typically
1889 set by the program running inside the pane and is not modified by tmate.
1890 It is the same mechanism used to set for example the xterm(1) window
1891 title in an X(7) window manager. Windows themselves do not have titles -
1892 a window's title is the title of its active pane. tmate itself may set
1893 the title of the terminal in which the client is running, see the
1894 set-titles option.
1895 A session's name is set with the new-session and rename-session commands.
1897 A window's name is set with one of:
1898 1. A command argument (such as -n for new-window or new-session).
1900 2. An escape sequence:
1902 $ printf '\033kWINDOW_NAME\033\\'
1904 3. Automatic renaming, which sets the name to the active command in
1906 the window's active pane. See the automatic-rename option.
1907 When a pane is first created, its title is the hostname. A pane's title
1909 can be set via the OSC title setting sequence, for example:
1910 $ printf '\033]2;My Title\033\\'
1912
1914 When the server is started, tmate copies the environment into the global
1915 environment; in addition, each session has a session environment. When a
1916 window is created, the session and global environments are merged. If a
1917 variable exists in both, the value from the session environment is used.
1918 The result is the initial environment passed to the new process.
1919 The update-environment session option may be used to update the session
1921 environment from the client when a new session is created or an old reat‐
1922 tached. tmate also initialises the TMUX variable with some internal
1923 information to allow commands to be executed from inside, and the TERM
1924 variable with the correct terminal setting of ‘screen’.
1925 Commands to alter and view the environment are:
1927 set-environment [-gru] [-t target-session] name [value]
1929 (alias: setenv)
1930 Set or unset an environment variable. If -g is used, the change
1931 is made in the global environment; otherwise, it is applied to
1932 the session environment for target-session. The -u flag unsets a
1933 variable. -r indicates the variable is to be removed from the
1934 environment before starting a new process.
1935 show-environment [-gs] [-t target-session] [variable]
1937 (alias: showenv)
1938 Display the environment for target-session or the global environ‐
1939 ment with -g. If variable is omitted, all variables are shown.
1940 Variables removed from the environment are prefixed with ‘-’. If
1941 -s is used, the output is formatted as a set of Bourne shell com‐
1942 mands.
1943
1945 tmate includes an optional status line which is displayed in the bottom
1946 line of each terminal. By default, the status line is enabled (it may be
1947 disabled with the status session option) and contains, from left-to-
1948 right: the name of the current session in square brackets; the window
1949 list; the title of the active pane in double quotes; and the time and
1950 date.
1951 The status line is made of three parts: configurable left and right sec‐
1953 tions (which may contain dynamic content such as the time or output from
1954 a shell command, see the status-left, status-left-length, status-right,
1955 and status-right-length options below), and a central window list. By
1956 default, the window list shows the index, name and (if any) flag of the
1957 windows present in the current session in ascending numerical order. It
1958 may be customised with the window-status-format and
1959 window-status-current-format options. The flag is one of the following
1960 symbols appended to the window name:
1961 Symbol Meaning
1963 * Denotes the current window.
1964 - Marks the last window (previously selected).
1965 # Window is monitored and activity has been detected.
1966 ! A bell has occurred in the window.
1967 ~ The window has been silent for the monitor-silence
1968 interval.
1969 M The window contains the marked pane.
1970 Z The window's active pane is zoomed.
1971 The # symbol relates to the monitor-activity window option. The window
1973 name is printed in inverted colours if an alert (bell, activity or
1974 silence) is present.
1975 The colour and attributes of the status line may be configured, the
1977 entire status line using the status-style session option and individual
1978 windows using the window-status-style window option.
1979 The status line is automatically refreshed at interval if it has changed,
1981 the interval may be controlled with the status-interval session option.
1982 Commands related to the status line are as follows:
1984 command-prompt [-I inputs] [-p prompts] [-t target-client] [template]
1986 Open the command prompt in a client. This may be used from
1987 inside tmate to execute commands interactively.
1988 If template is specified, it is used as the command. If present,
1990 -I is a comma-separated list of the initial text for each prompt.
1991 If -p is given, prompts is a comma-separated list of prompts
1992 which are displayed in order; otherwise a single prompt is dis‐
1993 played, constructed from template if it is present, or ‘:’ if
1994 not.
1995 Both inputs and prompts may contain the special character
1997 sequences supported by the status-left option.
1998 Before the command is executed, the first occurrence of the
2000 string ‘%%’ and all occurrences of ‘%1’ are replaced by the
2001 response to the first prompt, the second ‘%%’ and all ‘%2’ are
2002 replaced with the response to the second prompt, and so on for
2003 further prompts. Up to nine prompt responses may be replaced
2004 (‘%1’ to ‘%9’).
2005 confirm-before [-p prompt] [-t target-client] command
2007 (alias: confirm)
2008 Ask for confirmation before executing command. If -p is given,
2009 prompt is the prompt to display; otherwise a prompt is con‐
2010 structed from command. It may contain the special character
2011 sequences supported by the status-left option.
2012 This command works only from inside tmate.
2014 display-message [-p] [-c target-client] [-t target-pane] [message]
2016 (alias: display)
2017 Display a message. If -p is given, the output is printed to std‐
2018 out, otherwise it is displayed in the target-client status line.
2019 The format of message is described in the FORMATS section; infor‐
2020 mation is taken from target-pane if -t is given, otherwise the
2021 active pane for the session attached to target-client.
2022
2024 tmate maintains a set of named paste buffers. Each buffer may be either
2025 explicitly or automatically named. Explicitly named buffers are named
2026 when created with the set-buffer or load-buffer commands, or by renaming
2027 an automatically named buffer with set-buffer -n. Automatically named
2028 buffers are given a name such as ‘buffer0001’, ‘buffer0002’ and so on.
2029 When the buffer-limit option is reached, the oldest automatically named
2030 buffer is deleted. Explicitly named are not subject to buffer-limit and
2031 may be deleted with delete-buffer command.
2032 Buffers may be added using copy-mode or the set-buffer and load-buffer
2034 commands, and pasted into a window using the paste-buffer command. If a
2035 buffer command is used and no buffer is specified, the most recently
2036 added automatically named buffer is assumed.
2037 A configurable history buffer is also maintained for each window. By
2039 default, up to 2000 lines are kept; this can be altered with the
2040 history-limit option (see the set-option command above).
2041 The buffer commands are as follows:
2043 choose-buffer [-F format] [-t target-window] [template]
2045 Put a window into buffer choice mode, where a buffer may be cho‐
2046 sen interactively from a list. After a buffer is selected, ‘%%’
2047 is replaced by the buffer name in template and the result exe‐
2048 cuted as a command. If template is not given, "paste-buffer -b
2049 '%%'" is used. For the meaning of the -F flag, see the FORMATS
2050 section. This command works only if at least one client is
2051 attached.
2052 clear-history [-t target-pane]
2054 (alias: clearhist)
2055 Remove and free the history for the specified pane.
2056 delete-buffer [-b buffer-name]
2058 (alias: deleteb)
2059 Delete the buffer named buffer-name, or the most recently added
2060 automatically named buffer if not specified.
2061 list-buffers [-F format]
2063 (alias: lsb)
2064 List the global buffers. For the meaning of the -F flag, see the
2065 FORMATS section.
2066 load-buffer [-b buffer-name] path
2068 (alias: loadb)
2069 Load the contents of the specified paste buffer from path.
2070 paste-buffer [-dpr] [-b buffer-name] [-s separator] [-t target-pane]
2072 (alias: pasteb)
2073 Insert the contents of a paste buffer into the specified pane.
2074 If not specified, paste into the current one. With -d, also
2075 delete the paste buffer. When output, any linefeed (LF) charac‐
2076 ters in the paste buffer are replaced with a separator, by
2077 default carriage return (CR). A custom separator may be speci‐
2078 fied using the -s flag. The -r flag means to do no replacement
2079 (equivalent to a separator of LF). If -p is specified, paste
2080 bracket control codes are inserted around the buffer if the
2081 application has requested bracketed paste mode.
2082 save-buffer [-a] [-b buffer-name] path
2084 (alias: saveb)
2085 Save the contents of the specified paste buffer to path. The -a
2086 option appends to rather than overwriting the file.
2087 set-buffer [-a] [-b buffer-name] [-n new-buffer-name] data
2089 (alias: setb)
2090 Set the contents of the specified buffer to data. The -a option
2091 appends to rather than overwriting the buffer. The -n option
2092 renames the buffer to new-buffer-name.
2093 show-buffer [-b buffer-name]
2095 (alias: showb)
2096 Display the contents of the specified buffer.
2097
2099 Miscellaneous commands are as follows:
2100 clock-mode [-t target-pane]
2102 Display a large clock.
2103 if-shell [-bF] [-t target-pane] shell-command command [command]
2105 (alias: if)
2106 Execute the first command if shell-command returns success or the
2107 second command otherwise. Before being executed, shell-command
2108 is expanded using the rules specified in the FORMATS section,
2109 including those relevant to target-pane. With -b, shell-command
2110 is run in the background.
2111 If -F is given, shell-command is not executed but considered suc‐
2113 cess if neither empty nor zero (after formats are expanded).
2114 lock-server
2116 (alias: lock)
2117 Lock each client individually by running the command specified by
2118 the lock-command option.
2119 run-shell [-b] [-t target-pane] shell-command
2121 (alias: run)
2122 Execute shell-command in the background without creating a win‐
2123 dow. Before being executed, shell-command is expanded using the
2124 rules specified in the FORMATS section. With -b, the command is
2125 run in the background. After it finishes, any output to stdout
2126 is displayed in copy mode (in the pane specified by -t or the
2127 current pane if omitted). If the command doesn't return success,
2128 the exit status is also displayed.
2129 wait-for [-L | -S | -U] channel
2131 (alias: wait)
2132 When used without options, prevents the client from exiting until
2133 woken using wait-for -S with the same channel. When -L is used,
2134 the channel is locked and any clients that try to lock the same
2135 channel are made to wait until the channel is unlocked with
2136 wait-for -U. This command only works from outside tmate.
2137
2139 tmate understands some unofficial extensions to terminfo(5):
2140 Cs, Cr Set the cursor colour. The first takes a single string argument
2142 and is used to set the colour; the second takes no arguments and
2143 restores the default cursor colour. If set, a sequence such as
2144 this may be used to change the cursor colour from inside tmate:
2145 $ printf '\033]12;red\033\\'
2147 Ss, Se Set or reset the cursor style. If set, a sequence such as this
2149 may be used to change the cursor to an underline:
2150 $ printf '\033[4 q'
2152 If Se is not set, Ss with argument 0 will be used to reset the
2154 cursor style instead.
2155 Tc Indicate that the terminal supports the ‘direct colour’ RGB
2157 escape sequence (for example, \e[38;2;255;255;255m).
2158 Ms Store the current buffer in the host terminal's selection (clip‐
2160 board). See the set-clipboard option above and the xterm(1) man
2161 page.
2162
2164 tmate offers a textual interface called control mode. This allows appli‐
2165 cations to communicate with tmate using a simple text-only protocol.
2166 In control mode, a client sends tmate commands or command sequences ter‐
2168 minated by newlines on standard input. Each command will produce one
2169 block of output on standard output. An output block consists of a %begin
2170 line followed by the output (which may be empty). The output block ends
2171 with a %end or %error. %begin and matching %end or %error have two argu‐
2172 ments: an integer time (as seconds from epoch) and command number. For
2173 example:
2174 %begin 1363006971 2
2176 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
2177 %end 1363006971 2
2178 In control mode, tmate outputs notifications. A notification will never
2180 occur inside an output block.
2181 The following notifications are defined:
2183 %exit [reason]
2185 The tmate client is exiting immediately, either because it is not
2186 attached to any session or an error occurred. If present, reason
2187 describes why the client exited.
2188 %layout-change window-id window-layout window-visible-layout window-flags
2190 The layout of a window with ID window-id changed. The new layout
2191 is window-layout. The window's visible layout is
2192 window-visible-layout and the window flags are window-flags.
2193 %output pane-id value
2195 A window pane produced output. value escapes non-printable char‐
2196 acters and backslash as octal \xxx.
2197 %session-changed session-id name
2199 The client is now attached to the session with ID session-id,
2200 which is named name.
2201 %session-renamed name
2203 The current session was renamed to name.
2204 %sessions-changed
2206 A session was created or destroyed.
2207 %unlinked-window-add window-id
2209 The window with ID window-id was created but is not linked to the
2210 current session.
2211 %window-add window-id
2213 The window with ID window-id was linked to the current session.
2214 %window-close window-id
2216 The window with ID window-id closed.
2217 %window-renamed window-id name
2219 The window with ID window-id was renamed to name.
2220
2222 ~/.tmux.conf Default tmate configuration file.
2223 /etc/tmux.conf System-wide configuration file.
2224
2226 To create a new tmate session running vi(1):
2227 $ tmate new-session vi
2229 Most commands have a shorter form, known as an alias. For new-session,
2231 this is new:
2232 $ tmate new vi
2234 Alternatively, the shortest unambiguous form of a command is accepted.
2236 If there are several options, they are listed:
2237 $ tmate n
2239 ambiguous command: n, could be: new-session, new-window, next-window
2240 Within an active session, a new window may be created by typing ‘C-b c’
2242 (Ctrl followed by the ‘b’ key followed by the ‘c’ key).
2243 Windows may be navigated with: ‘C-b 0’ (to select window 0), ‘C-b 1’ (to
2245 select window 1), and so on; ‘C-b n’ to select the next window; and ‘C-b
2246 p’ to select the previous window.
2247 A session may be detached using ‘C-b d’ (or by an external event such as
2249 ssh(1) disconnection) and reattached with:
2250 $ tmate attach-session
2252 Typing ‘C-b ?’ lists the current key bindings in the current window; up
2254 and down may be used to navigate the list or ‘q’ to exit from it.
2255 Commands to be run when the tmate server is started may be placed in the
2257 ~/.tmux.conf configuration file. Common examples include:
2258 Changing the default prefix key:
2260 set-option -g prefix C-a
2262 unbind-key C-b
2263 bind-key C-a send-prefix
2264 Turning the status line off, or changing its colour:
2266 set-option -g status off
2268 set-option -g status-style bg=blue
2269 Setting other options, such as the default command, or locking after 30
2271 minutes of inactivity:
2272 set-option -g default-command "exec /bin/ksh"
2274 set-option -g lock-after-time 1800
2275 Creating new key bindings:
2277 bind-key b set-option status
2279 bind-key / command-prompt "split-window 'exec man %%'"
2280 bind-key S command-prompt "new-window -n %1 'ssh %1'"
2281
2283 pty(4)
2284
2286 Nicholas Marriott <nicholas.marriott@gmail.com>
2287BSD December 31, 2019 BSD