Skip to main content
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: 
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: 
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: 
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