> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/tmux/tmux/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Overview

> Understanding tmux command syntax, execution, and target specification

## 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:

```bash theme={null}
# 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.

```bash theme={null}
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

<ParamField path="target-client" type="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.
</ParamField>

List clients with `list-clients`.

### Target Session

<ParamField path="target-session" type="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
</ParamField>

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

<ParamField path="target-window" type="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
</ParamField>

**Window Special Tokens:**

| Token        | Short | Meaning                              |
| ------------ | ----- | ------------------------------------ |
| `{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

<ParamField path="target-pane" type="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`).
</ParamField>

If the pane index is omitted, the currently active pane in the specified window is used.

**Pane Special Tokens:**

| Token            | Short | Meaning                                  |
| ---------------- | ----- | ---------------------------------------- |
| `{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

<ParamField path="{mouse}" type="string">
  Alternative form: `=`. Specifies the session, window or pane where the most recent mouse event occurred.
</ParamField>

<ParamField path="{marked}" type="string">
  Alternative form: `~`. Specifies the marked pane (see `select-pane -m`).
</ParamField>

## 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

<ParamField path="shell-command" type="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.
</ParamField>

### Single Argument (via shell)

```bash theme={null}
new-window 'vi ~/.tmux.conf'
```

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

### Multiple Arguments (direct execution)

```bash theme={null}
$ 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.