Skip to main content

​
Command Syntax

tmux supports a large number of commands which can be used to control its behavior. Each command is named and can accept zero or more flags and arguments. Commands may be:
  • Bound to a key with the bind-key command
  • Run from the shell prompt
  • Executed from a shell script
  • Loaded from a configuration file
  • Entered at the command prompt

​
Example Command Usage

The same set-option command can be used in different contexts: 
# From the shell prompt
$ tmux set-option -g status-style bg=cyan

# In ~/.tmux.conf
set-option -g status-style bg=cyan

# Bound to a key
bind-key C set-option -g status-style bg=cyan

​
Command Parsing and Execution

tmux distinguishes between command parsing and execution:
  • Parsing: Splitting a command into its name and arguments
  • Execution: Running the parsed command

​
Command Queue

Each client has a command queue. Parsed commands are added to the queue and executed in order. Some commands like if-shell and run-shell stop execution until they complete.

​
Command Sequences

Commands separated by semicolons form a command sequence. If a command encounters an error, subsequent commands in the sequence are not executed. 
new-session; new-window
if-shell "true" "split-window"
kill-session

​
Specifying Targets

Most commands accept the -t (and sometimes -s) argument to specify which client, session, window, or pane should be affected.

​
Target Client

​
target-client
string
The name of the client, typically the pty file (e.g., /dev/ttyp1 or ttyp1). If no client is specified, tmux attempts to determine the current client.
List clients with list-clients.

​
Target Session

​
target-session
string
Specifies a session by:
  • Session ID prefixed with $ (e.g., $1)
  • Exact session name
  • Start of session name (e.g., mysess matches mysession)
  • Glob pattern matching the session name
Prefix with = for exact match only (e.g., =mysess matches only mysess, not mysession). If omitted, the current session is used, or if unavailable, the most recently used session.

​
Target Window

​
target-window
string
Specifies a window in the form session:window. The session follows the rules for target-session, and window is looked for as:
  • Special token (see below)
  • Window index (e.g., mysession:1)
  • Window ID (e.g., @1)
  • Exact window name
  • Start of window name
  • Glob pattern matching window name
Window Special Tokens:
TokenShortMeaning
{start}^The lowest-numbered window
{end}$The highest-numbered window
{last}!The last (previously current) window
{next}+The next window by number
{previous}-The previous window by number
{current}@The current window
Example: select-window -t:+2 (select window 2 positions ahead)

​
Target Pane

​
target-pane
string
May be a pane ID or takes a similar form to target-window with optional addition of a period followed by a pane index or ID (e.g., mysession:mywindow.1).
If the pane index is omitted, the currently active pane in the specified window is used. Pane Special Tokens:
TokenShortMeaning
{last}!The last (previously active) pane
{next}+The next pane by number
{previous}-The previous pane by number
{top}The top pane
{bottom}The bottom pane
{left}The leftmost pane
{right}The rightmost pane
{top-left}The top-left pane
{top-right}The top-right pane
{bottom-left}The bottom-left pane
{bottom-right}The bottom-right pane
{up-of}The pane above the active pane
{down-of}The pane below the active pane
{left-of}The pane to the left of the active pane
{right-of}The pane to the right of the active pane
{active}@The active pane

​
Special Target Tokens

​
{mouse}
string
Alternative form: =. Specifies the session, window or pane where the most recent mouse event occurred.
​
{marked}
string
Alternative form: ~. Specifies the marked pane (see select-pane -m).

​
Unique IDs

Sessions, windows, and panes each have a unique ID:
  • Session IDs: Prefixed with $ (e.g., $1)
  • Window IDs: Prefixed with @ (e.g., @1)
  • Pane IDs: Prefixed with % (e.g., %1)
These IDs are unique and unchanged for the life of the session, window, or pane. The pane ID is passed to the child process in the TMUX_PANE environment variable. Display IDs using format variables: #{session_id}, #{window_id}, #{pane_id}.

​
Shell Commands

​
shell-command
string
Shell commands are executed via /bin/sh -c. Some commands (new-window, new-session, split-window, respawn-window, respawn-pane) allow shell-command as multiple arguments, executing directly without invoking the shell.

​
Single Argument (via shell)

new-window 'vi ~/.tmux.conf'
Runs: /bin/sh -c 'vi ~/.tmux.conf'

​
Multiple Arguments (direct execution)

$ tmux new-window vi ~/.tmux.conf
Runs vi directly without invoking the shell.

​
Command Flags

Most commands support various flags that modify their behavior:
  • Flags are specified with a single dash (e.g., -t, -d, -v)
  • Some flags take arguments (e.g., -t target-pane)
  • Flags can often be combined (e.g., -dP)
  • Order of flags typically doesn’t matter

​
Common Command Patterns

​
Format Specifications

Many commands accept -F format to control output format using format variables.

​
Filters

List commands often accept -f filter to filter results based on format expressions.

​
Sort Order

List commands may accept -O sort-order to specify sorting and -r to reverse the order.

Build docs developers (and LLMs) love

Get started for freeTalk to us