Skip to main content

​
Overview

Clients are terminal connections to the tmux server. Each client is attached to a session to interact with it. Multiple clients can be attached to the same session.

​
refresh-client

Alias: refresh 
refresh-client [-cDlLRSU] [-A pane:state] [-B name:what:format] [-C size] 
               [-f flags] [-r pane:report] [-t target-client] [adjustment]
Refresh the current client if bound to a key, or a single client if one is given with -t.
​
-c
flag
Return to tracking the cursor automatically. The visible portion follows the cursor.
​
-D
flag
Move the visible portion of the window down by adjustment rows (default 1).
​
-l
flag
Request the clipboard from the client using the xterm escape sequence.
​
-L
flag
Move the visible portion left by adjustment columns.
​
-R
flag
Move the visible portion right by adjustment columns.
​
-S
flag
Only update the client’s status line.
​
-U
flag
Move the visible portion up by adjustment rows.
​
-A
string
Allow a control mode client to trigger actions on a pane. Format: pane-id:state where state is on, off, continue, or pause.
  • off: Stop sending output from pane to client
  • continue: Resume sending output if paused
  • pause: Pause the pane
May be given multiple times for different panes.
​
-B
string
Set a subscription to a format for a control mode client. Format: name:what:format
  • name: Name for the subscription
  • what: Item to subscribe to (pane ID like %0, %* for all panes, window ID like @0, @* for all windows, or empty for session)
  • format: The format string
Changes reported via %subscription-changed notification. Pass only name to remove subscription.
​
-C
string
Set the width and height of a control mode client. Format: widthxheight or window-id:widthxheight (e.g., 80x24 or @0:80x24).
​
-f
string
Set comma-separated list of client flags (see attach-session).
​
-r
string
Provide information about a pane via a report in control mode. Format: pane-id:report where report is an escape sequence.
​
-t
string
The target client.
​
adjustment
number
Number of rows or columns to move by (default 1).

​
Visible Portion Control

The visible position is a property of the client. When a window is larger than the client, only a portion is visible. Use -U, -D, -L, -R to pan, and -c to return to following the cursor.

​
Examples

# Refresh the current client
refresh-client

# Update only the status line
refresh-client -S

# Pan the visible portion up by 5 rows
refresh-client -U 5

# Return to cursor tracking
refresh-client -c

# Set client size in control mode
refresh-client -C 80x24

​
list-clients

Alias: lsc 
list-clients [-r] [-F format] [-f filter] [-O sort-order] [-t target-session]
List all clients attached to the server.
​
-r
flag
Reverse the sort order.
​
-F
string
Specify the format of each line. Available client format variables:
  • #{client_name}: Name of client
  • #{client_tty}: Pseudo terminal of client
  • #{client_width}, #{client_height}: Client dimensions
  • #{client_created}: Time client was created
  • #{client_activity}: Time of last activity
  • #{client_session}: Name of attached session
  • #{client_prefix}: 1 if prefix key has been pressed
  • #{client_readonly}: 1 if client is read-only
​
-f
string
Only show clients for which the filter is true.
​
-O
string
Specify sort order: name, size, creation (time), or activity (time).
​
-t
string
List only clients connected to the target session.

​
Examples

# List all clients
list-clients

# List with custom format
list-clients -F "#{client_name}: #{client_session}"

# List clients for specific session
list-clients -t mysession

# List sorted by activity
list-clients -O activity

​
lock-client

Alias: lockc 
lock-client [-t target-client]
Lock the target client. Runs the command specified by the lock-command option.
​
-t
string
The target client to lock.

​
Examples

# Lock current client
lock-client

# Lock specific client
lock-client -t /dev/pts/1

​
suspend-client

Alias: suspendc 
suspend-client [-t target-client]
Suspend a client by sending SIGTSTP (tty stop signal).
​
-t
string
The target client to suspend.

​
Examples

# Suspend current client
suspend-client

# Suspend specific client
suspend-client -t /dev/pts/1

​
display-message

Alias: display 
display-message [-aINpv] [-c target-client] [-d delay] [-F format] 
                [-t target-pane] [message]
Display a message in the status line or print it to stdout.
​
-a
flag
List the format variables and their values.
​
-I
flag
Forward any input read from stdin to the empty pane given by target-pane.
​
-N
flag
Ignore keys pressed while the message is displayed.
​
-p
flag
Print the message to stdout instead of displaying in status line.
​
-v
flag
Print verbose logging as the format is parsed.
​
-c
string
The target client.
​
-d
number
Duration in milliseconds for which the message is shown. Default uses the display-time option.
​
-F
string
Format string. Overrides the message argument.
​
-t
string
The target pane for context.
​
message
string
Message to display. Can include format variables.

​
Examples

# Display a simple message
display-message "Hello, World!"

# Display with format variables
display-message "Session: #{session_name}, Window: #{window_index}"

# Print to stdout
display-message -p "#{pane_current_path}"

# Display for 2 seconds
display-message -d 2000 "Custom duration"

# List all format variables
display-message -a

# Use -F for format
display-message -p -F "#{window_name}"

​
show-messages

Alias: showmsgs 
show-messages [-JT] [-t target-client]
Show server messages or jobs. Messages are stored in a per-client queue.
​
-J
flag
Show jobs instead of messages.
​
-T
flag
Show debugging information about the format tree.
​
-t
string
The target client.

​
Examples

# Show messages for current client
show-messages

# Show messages for specific client
show-messages -t /dev/pts/1

# Show running jobs
show-messages -J

​
display-menu

Alias: menu 
display-menu [-O] [-c target-client] [-t target-pane] [-T title] [-x position] 
             [-y position] name key command ...
Display a menu on the target client.
​
-O
flag
Do not close the menu after an item is selected.
​
-c
string
The target client.
​
-t
string
The target pane.
​
-T
string
Title for the menu.
​
-x
string
Horizontal position. Can be a number, C for center, R for right, P for mouse position, M for mouse menu position, W for window position, or S for status line position.
​
-y
string
Vertical position. Same options as -x for vertical positioning.
​
name
string
required
Menu item name (displayed text). Use empty string for separator.
​
key
string
required
Key shortcut for the item. Use empty string for no shortcut.
​
command
string
required
Command to execute when item is selected. Use empty string for separator.
Menu items are specified in triplets: name, key, command. Repeat for each menu item.

​
Examples

# Simple menu
display-menu -T "My Menu" \
  "New Window" "c" "new-window" \
  "Split Horizontal" "|" "split-window -h" \
  "" "" "" \
  "Kill Pane" "x" "kill-pane"

# Menu at mouse position
display-menu -x M -y M \
  "Vertical Split" "v" "split-window -v" \
  "Horizontal Split" "h" "split-window -h"

# Menu in center
display-menu -x C -y C -T "Layout" \
  "Even Horizontal" "1" "select-layout even-horizontal" \
  "Even Vertical" "2" "select-layout even-vertical" \
  "Tiled" "3" "select-layout tiled"

​
display-popup

Alias: popup 
display-popup [-CE] [-c target-client] [-d start-directory] [-h height] 
              [-t target-pane] [-T title] [-w width] [-x position] 
              [-y position] [shell-command]
Display a popup on the target client.
​
-C
flag
Close any popup already open.
​
-E
flag
Close the popup automatically when the shell command exits.
​
-c
string
The target client.
​
-d
string
Starting directory for the shell command.
​
-h
string
Height of the popup. Can be a number or percentage (e.g., 50%).
​
-t
string
The target pane.
​
-T
string
Title for the popup.
​
-w
string
Width of the popup. Can be a number or percentage.
​
-x
string
Horizontal position. Same options as display-menu -x.
​
-y
string
Vertical position. Same options as display-menu -y.
​
shell-command
string
Shell command to run in the popup.

​
Examples

# Simple popup with command
display-popup -E "top"

# Centered popup with specific size
display-popup -x C -y C -w 80% -h 80% -E "htop"

# Popup with title
display-popup -T "File Browser" -E "ranger"

# Close any open popup
display-popup -C

​
choose-client

choose-client [-NrZ] [-F format] [-f filter] [-K key-format] [-O sort-order] 
              [-t target-pane] [template]
Put a pane into client mode, where a client may be chosen interactively from a list.
​
-N
flag
Start without the preview.
​
-r
flag
Reverse the sort order.
​
-Z
flag
Zoom the pane.
​
-F
string
Format for each item in the list.
​
-f
string
Initial filter (as a format expression).
​
-K
string
Format for each shortcut key.
​
-O
string
Initial sort order: name, size, creation, or activity.
​
-t
string
Target pane.
​
template
string
After a client is chosen, %% is replaced by the client name and the result is executed as a command.

​
Examples

# Choose client interactively
choose-client

# Choose to detach a client
choose-client "detach-client -t '%%'"

​
Control Mode

Control mode (tmux -C) is a special mode where tmux acts as a background daemon and communicates with a client program via a simple text protocol. In control mode:
  • Output is sent as notifications
  • Input is parsed as commands
  • No terminal UI is displayed
  • Useful for integrating tmux with other programs

​
Control Mode Client Flags

  • no-output: Client does not receive pane output
  • pause-after=seconds: Pause output when behind
  • read-only: Client is read-only
  • wait-exit: Wait for empty line before exiting

​
Control Mode Notifications

  • %output: Pane output
  • %layout-change: Window layout changed
  • %session-changed: Session changed
  • %window-add, %window-close: Window events
  • %subscription-changed: Format subscription changed