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
16 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
21 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
30 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
34 $ tmate attach
35
36 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
40 The options are as follows:
41
42 -2 Force tmate to assume the terminal supports 256 colours.
43
44 -C Start in control mode (see the CONTROL MODE section).
45 Given twice (-CC) disables echo.
46
47 -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
53 -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
58 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
64 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
68 -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
76 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
81 -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
85 -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
90 -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
96 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
100 -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
106 -V Report the tmate version.
107
108 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
118 The default command key bindings are:
119
120 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
185 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
193 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
199 target-session is tried as, in order:
200
201 1. A session ID prefixed with a $.
202
203 2. An exact name of a session (as listed by the list-sessions
204 command).
205
206 3. The start of a session name, for example ‘mysess’ would match
207 a session named ‘mysession’.
208
209 4. An fnmatch(3) pattern which is matched against the session
210 name.
211
212 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
216 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
221 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
225 1. A special token, listed below.
226
227 2. A window index, for example ‘mysession:1’ is window 1 in ses‐
228 sion ‘mysession’.
229
230 3. A window ID, such as @1.
231
232 4. An exact window name, such as ‘mysession:mywindow’.
233
234 5. The start of a window name, such as ‘mysession:mywin’.
235
236 6. As an fnmatch(3) pattern matched against the window name.
237
238 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
243 The following special tokens are available to indicate particular win‐
244 dows. Each has a single-character alternative form.
245
246 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
253 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
259 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
276 The tokens ‘+’ and ‘-’ may be followed by an offset, for example:
277
278 select-window -t:+2
279
280 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
285 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
294 shell-command arguments are sh(1) commands. This may be a single argu‐
295 ment passed to the shell, for example:
296
297 new-window 'vi /etc/passwd'
298
299 Will run:
300
301 /bin/sh -c 'vi /etc/passwd'
302
303 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
308 $ tmate new-window vi /etc/passwd
309
310 Will run vi(1) directly without invoking the shell.
311
312 command [arguments] refers to a tmate command, passed with the command
313 and arguments separately, for example:
314
315 bind-key F1 set-window-option force-width 81
316
317 Or if using sh(1):
318
319 $ tmate bind-key F1 set-window-option force-width 81
320
321 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
329 Example tmate commands include:
330
331 refresh-client -t/dev/ttyp2
332
333 rename-session -tfirst newname
334
335 set-window-option -t:0 monitor-activity on
336
337 new-window ; split-window -d
338
339 bind-key R source-file ~/.tmux.conf \; \
340 display-message "source-file done"
341
342 Or from sh(1):
343
344 $ tmate kill-window -t :1
345
346 $ tmate new-window \; split-window -d
347
348 $ 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
360 The following commands are available to manage clients and sessions:
361
362 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
371 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
375 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
379 -c will set the session working directory (used for new windows)
380 to working-directory.
381
382 If -E is used, the update-environment option will not be applied.
383
384 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
392 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
397 kill-server
398 Kill the tmate server and clients and destroy all sessions.
399
400 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
407 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
413 list-commands
414 (alias: lscm)
415 List the syntax of all commands supported by tmate.
416
417 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
422 lock-client [-t target-client]
423 (alias: lockc)
424 Lock target-client, see the lock-server command.
425
426 lock-session [-t target-session]
427 (alias: locks)
428 Lock all clients attached to target-session.
429
430 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
436 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
442 If run from a terminal, any termios(4) special characters are
443 saved and used for new windows in the new session.
444
445 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
449 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
458 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
463 If -E is used, the update-environment option will not be applied.
464
465 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
471 rename-session [-t target-session] new-name
472 (alias: rename)
473 Rename the session to new-name.
474
475 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
483 source-file path
484 (alias: source)
485 Execute commands from path.
486
487 start-server
488 (alias: start)
489 Start the tmate server, if not already running, without creating
490 any sessions.
491
492 suspend-client [-t target-client]
493 (alias: suspendc)
494 Suspend a client by sending SIGTSTP (tty stop).
495
496 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
504 If -E is used, update-environment option will not be applied.
505
506 -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
511 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
524 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
528 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
578 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
585 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
589 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
595 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
607 bind-key -temacs-copy C-w copy-selection -x
608 bind-key -temacs-copy C-q copy-pipe "cat >/tmp/out"
609
610 The paste buffer key pastes the first line from the top paste buffer on
611 the stack.
612
613 The synopsis for the copy-mode command is:
614
615 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
624 bind PageUp copy-mode -eu
625
626 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
636 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
641 The following layouts are supported:
642
643 even-horizontal
644 Panes are spread out evenly from left to right across the window.
645
646 even-vertical
647 Panes are spread evenly from top to bottom.
648
649 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
655 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
660 tiled Panes are spread out as evenly as possible over the window in
661 both rows and columns.
662
663 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
667 $ 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
672 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
676 Commands related to windows and panes are as follows:
677
678 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
687 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
702 -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
708 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
717 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
726 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
733 Note that the choose-window and choose-session commands are wrap‐
734 pers around choose-tree.
735
736 If -s is given, will show sessions. If -w is given, will show
737 windows.
738
739 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
743 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
751 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
756 This command works only if at least one client is attached.
757
758 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
767 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
774 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
785 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
792 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
795 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
801 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
807 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
812 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
818 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
827 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
835 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
841 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
846 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
852 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
859 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
867 When the shell command completes, the window closes. See the
868 remain-on-exit option to change this behaviour.
869
870 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
875 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
880 next-layout [-t target-window]
881 (alias: nextl)
882 Move a window to the next layout and rearrange the panes to fit.
883
884 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
889 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
898 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
901 bind-key C-p pipe-pane -o 'cat >>~/output.#I-#P'
902
903 previous-layout [-t target-window]
904 (alias: prevl)
905 Move to the previous layout in the session.
906
907 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
912 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
917 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
924 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
928 -M begins mouse resizing (only valid if bound to a mouse key
929 binding, see MOUSE SUPPORT).
930
931 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
939 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
947 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
952 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
960 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
968 -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
973 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
978 select-pane -t:.1 -P 'bg=red'
979
980 -g shows the current pane style.
981
982 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
989 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
1001 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
1008 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
1011 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
1017 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
1021 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
1038 bind-key '"' split-window
1039 bind-key "'" new-window
1040
1041 Commands related to key bindings are as follows:
1042
1043 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
1057 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
1062 To view the default bindings and possible commands, see the
1063 list-keys command.
1064
1065 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
1070 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
1074 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
1083 -M passes through a mouse event (only valid if bound to a mouse
1084 key binding, see MOUSE SUPPORT).
1085
1086 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
1090 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
1100 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
1104 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
1111 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
1117 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
1121 $ tmate setw -q @foo "abc123"
1122 $ tmate showw -v @foo
1123 abc123
1124
1125 Commands which set options are as follows:
1126
1127 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
1136 The -o flag prevents setting an option that is already set and
1137 the -q flag suppresses errors about unknown or ambiguous options.
1138
1139 With -a, and if the option expects a string or a style, value is
1140 appended to the existing setting. For example:
1141
1142 set -g status-left "foo"
1143 set -ag status-left "bar"
1144
1145 Will result in ‘foobar’. And:
1146
1147 set -g status-style "bg=red"
1148 set -ag status-style "fg=blue"
1149
1150 Will result in a red background and blue foreground. Without -a,
1151 the result would be the default background and a blue foreground.
1152
1153 Available window options are listed under set-window-option.
1154
1155 value depends on the option and may be a number, a string, or a
1156 flag (on, off, or omitted to toggle).
1157
1158 Available server options are:
1159
1160 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
1165 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
1171 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
1177 exit-unattached [on | off]
1178 If enabled, the server will exit when there are no
1179 attached clients.
1180
1181 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
1187 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
1191 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
1195 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
1203 disallowedWindowOps: 20,21,SetXprop
1204
1205 Or changing this property from the xterm(1) interactive
1206 menu when required.
1207
1208 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
1215 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
1220 "*:clear=\e[H\e[2J,rxvt:dch1=\e[P"
1221
1222 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
1227 "*256col*:colors=256,xterm*:XT"
1228
1229 Available session options are:
1230
1231 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
1237 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
1242 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
1250 bell-on-alert [on | off]
1251 If on, ring the terminal bell when an alert occurs.
1252
1253 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
1260 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
1270 destroy-unattached [on | off]
1271 If enabled and the session is no longer attached to any
1272 clients, it is destroyed.
1273
1274 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
1280 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
1284 display-panes-colour colour
1285 Set the colour used by the display-panes command to show
1286 the indicators for inactive panes.
1287
1288 display-panes-time time
1289 Set the time in milliseconds for which the indicators
1290 shown by the display-panes command appear.
1291
1292 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
1298 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
1304 key-table key-table
1305 Set the default key table to key-table instead of root.
1306
1307 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
1312 lock-command shell-command
1313 Command to run when locking each client. The default is
1314 to run lock(1) with -np.
1315
1316 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
1320 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
1324 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
1331 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
1336 Examples are:
1337
1338 fg=yellow,bold,underscore,blink
1339 bg=black,fg=default,noreverse
1340
1341 With the -a flag to the set-option command the new style
1342 is added otherwise the existing style is replaced.
1343
1344 message-style style
1345 Set status line message style. For how to specify style,
1346 see the message-command-style option.
1347
1348 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
1353 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
1358 prefix2 key
1359 Set a secondary key accepted as a prefix key. Like
1360 prefix, prefix2 can be set to ‘None’.
1361
1362 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
1368 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
1376 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
1384 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
1391 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
1395 status [on | off]
1396 Show or hide the status line.
1397
1398 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
1403 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
1407 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
1413 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
1420 Character pair Replaced with
1421 #[attributes] Colour or attribute change
1422 ## A literal ‘#’
1423
1424 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
1428 Examples are:
1429
1430 #(sysctl vm.loadavg)
1431 #[fg=yellow,bold]#(apm -l)%%#[default] [#S]
1432
1433 The default is ‘[#S] ’.
1434
1435 status-left-length length
1436 Set the maximum length of the left component of the sta‐
1437 tus bar. The default is 10.
1438
1439 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
1444 status-position [top | bottom]
1445 Set the position of the status line.
1446
1447 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
1454 status-right-length length
1455 Set the maximum length of the right component of the sta‐
1456 tus bar. The default is 40.
1457
1458 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
1463 status-style style
1464 Set status line style. For how to specify style, see the
1465 message-command-style option.
1466
1467 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
1478 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
1483 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
1489 visual-silence [on | off]
1490 If monitor-silence is enabled, prints a message after the
1491 interval has expired on a given window.
1492
1493 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
1499 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
1504 Supported window options are:
1505
1506 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
1516 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
1520 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
1530 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
1540 set-window-option -g automatic-rename off
1541
1542 automatic-rename-format format
1543 The format (see FORMATS) used when the automatic-rename
1544 option is enabled.
1545
1546 clock-mode-colour colour
1547 Set clock colour.
1548
1549 clock-mode-style [12 | 24]
1550 Set clock hour format.
1551
1552 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
1558 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
1563 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
1568 mode-style style
1569 Set window modes style. For how to specify style, see
1570 the message-command-style option.
1571
1572 monitor-activity [on | off]
1573 Monitor for activity in the window. Windows with activ‐
1574 ity are highlighted in the status line.
1575
1576 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
1582 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
1590 other-pane-width width
1591 Like other-pane-height, but set the width of other panes
1592 in the main-vertical layout.
1593
1594 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
1599 pane-base-index index
1600 Like base-index, but set the starting index for pane num‐
1601 bers.
1602
1603 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
1608 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
1613 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
1618 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
1622 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
1627 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
1632 window-status-current-format string
1633 Like window-status-format, but is the format used when
1634 the window is the current window.
1635
1636 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
1641 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
1647 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
1652 window-status-separator string
1653 Sets the separator drawn between windows in the status
1654 line. The default is a single space character.
1655
1656 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
1660 window-style style
1661 Set the default window style. For how to specify style,
1662 see the message-command-style option.
1663
1664 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
1670 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
1674 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
1683 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
1693 alert-activity Run when a window has activity. See monitor-activity.
1694
1695 alert-bell Run when a window has received a bell.
1696
1697 alert-silence Run when a window has been silent. See
1698 monitor-silence.
1699
1700 client-attached Run when a client is attached.
1701
1702 client-detached Run when a client is detached
1703
1704 client-resized Run when a client is resized.
1705
1706 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
1709 pane-exited Run when the program running in a pane exits.
1710
1711 Hooks are managed with these commands:
1712
1713 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
1719 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
1730 MouseDown1 MouseUp1 MouseDrag1 MouseDragEnd1
1731 MouseDown2 MouseUp2 MouseDrag2 MouseDragEnd2
1732 MouseDown3 MouseUp3 MouseDrag3 MouseDragEnd3
1733 WheelUp WheelDown
1734
1735 Each should be suffixed with a location, for example ‘MouseDown1Status’.
1736
1737 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
1744 The send-keys -M flag may be used to forward a mouse event to a pane.
1745
1746 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
1758 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
1766 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
1777 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
1785 The following variables are available, where appropriate:
1786
1787 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
1896 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
1899 1. A command argument (such as -n for new-window or new-session).
1900
1901 2. An escape sequence:
1902
1903 $ printf '\033kWINDOW_NAME\033\\'
1904
1905 3. Automatic renaming, which sets the name to the active command in
1906 the window's active pane. See the automatic-rename option.
1907
1908 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
1911 $ 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
1920 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
1926 Commands to alter and view the environment are:
1927
1928 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
1936 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
1952 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
1962 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
1972 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
1976 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
1980 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
1983 Commands related to the status line are as follows:
1984
1985 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
1989 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
1996 Both inputs and prompts may contain the special character
1997 sequences supported by the status-left option.
1998
1999 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
2006 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
2013 This command works only from inside tmate.
2014
2015 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
2033 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
2038 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
2042 The buffer commands are as follows:
2043
2044 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
2053 clear-history [-t target-pane]
2054 (alias: clearhist)
2055 Remove and free the history for the specified pane.
2056
2057 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
2062 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
2067 load-buffer [-b buffer-name] path
2068 (alias: loadb)
2069 Load the contents of the specified paste buffer from path.
2070
2071 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
2083 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
2088 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
2094 show-buffer [-b buffer-name]
2095 (alias: showb)
2096 Display the contents of the specified buffer.
2097
2099 Miscellaneous commands are as follows:
2100
2101 clock-mode [-t target-pane]
2102 Display a large clock.
2103
2104 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
2112 If -F is given, shell-command is not executed but considered suc‐
2113 cess if neither empty nor zero (after formats are expanded).
2114
2115 lock-server
2116 (alias: lock)
2117 Lock each client individually by running the command specified by
2118 the lock-command option.
2119
2120 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
2130 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
2141 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
2146 $ printf '\033]12;red\033\\'
2147
2148 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
2151 $ printf '\033[4 q'
2152
2153 If Se is not set, Ss with argument 0 will be used to reset the
2154 cursor style instead.
2155
2156 Tc Indicate that the terminal supports the ‘direct colour’ RGB
2157 escape sequence (for example, \e[38;2;255;255;255m).
2158
2159 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
2167 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
2175 %begin 1363006971 2
2176 0: ksh* (1 panes) [80x24] [layout b25f,80x24,0,0,2] @2 (active)
2177 %end 1363006971 2
2178
2179 In control mode, tmate outputs notifications. A notification will never
2180 occur inside an output block.
2181
2182 The following notifications are defined:
2183
2184 %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
2189 %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
2194 %output pane-id value
2195 A window pane produced output. value escapes non-printable char‐
2196 acters and backslash as octal \xxx.
2197
2198 %session-changed session-id name
2199 The client is now attached to the session with ID session-id,
2200 which is named name.
2201
2202 %session-renamed name
2203 The current session was renamed to name.
2204
2205 %sessions-changed
2206 A session was created or destroyed.
2207
2208 %unlinked-window-add window-id
2209 The window with ID window-id was created but is not linked to the
2210 current session.
2211
2212 %window-add window-id
2213 The window with ID window-id was linked to the current session.
2214
2215 %window-close window-id
2216 The window with ID window-id closed.
2217
2218 %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
2228 $ tmate new-session vi
2229
2230 Most commands have a shorter form, known as an alias. For new-session,
2231 this is new:
2232
2233 $ tmate new vi
2234
2235 Alternatively, the shortest unambiguous form of a command is accepted.
2236 If there are several options, they are listed:
2237
2238 $ tmate n
2239 ambiguous command: n, could be: new-session, new-window, next-window
2240
2241 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
2244 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
2248 A session may be detached using ‘C-b d’ (or by an external event such as
2249 ssh(1) disconnection) and reattached with:
2250
2251 $ tmate attach-session
2252
2253 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
2256 Commands to be run when the tmate server is started may be placed in the
2257 ~/.tmux.conf configuration file. Common examples include:
2258
2259 Changing the default prefix key:
2260
2261 set-option -g prefix C-a
2262 unbind-key C-b
2263 bind-key C-a send-prefix
2264
2265 Turning the status line off, or changing its colour:
2266
2267 set-option -g status off
2268 set-option -g status-style bg=blue
2269
2270 Setting other options, such as the default command, or locking after 30
2271 minutes of inactivity:
2272
2273 set-option -g default-command "exec /bin/ksh"
2274 set-option -g lock-after-time 1800
2275
2276 Creating new key bindings:
2277
2278 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>
2287
2288BSD December 31, 2019 BSD