Pane Commands

Manage panes (split containers) in cmux workspaces

Panes are containers for surfaces within a workspace. Each workspace has a split layout tree of panes.

list-panes

List all panes in the current or specified workspace.

cmux list-panes [--workspace <id|ref|index>]

Flags:

--workspace · string

Workspace to list panes from (defaults to $CMUX_WORKSPACE_ID)

--json · boolean

Output results in JSON format

--id-format · string

Control ID output format: refs, uuids, or both

Output (text):

* pane:1  [2 surfaces]  [focused]
  pane:2  [1 surface]
  pane:3  [3 surfaces]

Output (JSON):

{
  "panes": [
    {
      "ref": "pane:1",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "index": 1,
      "focused": true,
      "surface_count": 2
    }
  ]
}

new-pane

Create a new pane with a split direction.

cmux new-pane [--workspace <id|ref|index>] [--direction <direction>] [--type <terminal|browser>] [--url <url>]

Flags:

--workspace · string

Workspace context (defaults to $CMUX_WORKSPACE_ID)

--direction · string

Split direction: left, right, up, or down (default: right)

--type · string

Initial surface type: terminal or browser

--url · string

URL to open (for browser surfaces)

Examples:

Default Right Split

cmux new-pane

Output:

OK surface=surface:5 pane=pane:3 workspace=workspace:1

focus-pane

Focus a specific pane by ID, ref, or index.

cmux focus-pane --pane <id|ref|index> [--workspace <id|ref|index>]

Flags:

--pane · string · required

Pane to focus (ID, ref, or index)

--workspace · string

Workspace context (defaults to $CMUX_WORKSPACE_ID)

Examples:

By Ref

cmux focus-pane --pane pane:2

Output:

OK pane=pane:2 workspace=workspace:1

list-pane-surfaces

List all surfaces within a specific pane.

cmux list-pane-surfaces --pane <id|ref|index> [--workspace <id|ref|index>]

Flags:

--pane · string · required

Pane to list surfaces from (ID, ref, or index)

--workspace · string

Workspace context (defaults to $CMUX_WORKSPACE_ID)

--json · boolean

Output results in JSON format

--id-format · string

Control ID output format: refs, uuids, or both

Examples:

By Ref

cmux list-pane-surfaces --pane pane:1

Output (text):

* surface:1  ~/projects/app  [selected]
  surface:2  npm run dev
  surface:3  git status

Output (JSON):

{
  "surfaces": [
    {
      "ref": "surface:1",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "~/projects/app",
      "selected": true,
      "index": 1
    }
  ]
}

tree

Display the pane/surface hierarchy tree for a workspace.

cmux tree [--workspace <id|ref|index>]

Flags:

--workspace · string

Workspace to display tree for (defaults to current workspace)

--json · boolean

Output results in JSON format

--id-format · string

Control ID output format: refs, uuids, or both

Example:

cmux tree

Output: Displays a hierarchical tree view of panes and surfaces in the workspace.

Global Flags

These flags can be used with most pane commands:

--socket · string

Path to the cmux socket (default: /tmp/cmux.sock or $CMUX_SOCKET_PATH)

--password · string

Socket authentication password (or use $CMUX_SOCKET_PASSWORD)

--json · boolean

Output results in JSON format

--id-format · string

Control ID output format: refs, uuids, or both