Client Commands

Commands for managing and controlling tmux clients

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