Skip to main content
Surfaces are individual terminal or browser panels within panes. Each pane can contain one or more surfaces stacked vertically.

​
list-panels

List all surfaces in the current or specified workspace (legacy alias for surface listing). 
cmux list-panels [--workspace <id|ref|index>]
Flags:
​
--workspace
string
Workspace to list surfaces 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): 
* surface:1  terminal  [focused]  "~/projects/app"
  surface:2  browser
  surface:3  terminal  "npm run dev"
Output (JSON): 
{
  "surfaces": [
    {
      "ref": "surface:1",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "terminal",
      "title": "~/projects/app",
      "focused": true,
      "index": 1
    }
  ]
}

​
new-surface

Create a new surface in the current or specified pane. 
cmux new-surface [--workspace <id|ref|index>] [--pane <id|ref|index>] [--type <terminal|browser>] [--url <url>]
Flags:
​
--workspace
string
Workspace context (defaults to $CMUX_WORKSPACE_ID)
​
--pane
string
Pane to add surface to (defaults to current pane)
​
--type
string
Surface type: terminal or browser
​
--url
string
URL to open (for browser surfaces)
Examples: 
cmux new-surface
Output: 
OK surface=surface:4 pane=pane:1 workspace=workspace:1

​
close-surface

Close a specific surface. 
cmux close-surface [--workspace <id|ref|index>] [--surface <id|ref|index>]
Flags:
​
--workspace
string
Workspace context (defaults to $CMUX_WORKSPACE_ID)
​
--surface
string
Surface to close (defaults to $CMUX_SURFACE_ID)
​
--panel
string
Legacy alias for --surface
Examples: 
cmux close-surface
Output: 
OK

​
focus-panel

Focus a specific surface (panel). 
cmux focus-panel --panel <id|ref|index> [--workspace <id|ref|index>]
Flags:
​
--panel
string
required
Surface to focus (ID, ref, or index)
​
--workspace
string
Workspace context (defaults to $CMUX_WORKSPACE_ID)
Examples: 
cmux focus-panel --panel surface:2
Output: 
OK

​
new-split

Create a new split pane with a surface. 
cmux new-split <direction> [--workspace <id|ref|index>] [--surface <id|ref|index>]
Arguments:
​
direction
string
required
Split direction: left, right, up, or down
Flags:
​
--workspace
string
Workspace context (defaults to $CMUX_WORKSPACE_ID)
​
--surface
string
Reference surface to split from (defaults to $CMUX_SURFACE_ID)
​
--panel
string
Legacy alias for --surface
Examples: 
cmux new-split right
Output: 
OK

​
move-surface

Move a surface to a different pane, workspace, or window. 
cmux move-surface --surface <id|ref|index> [--pane <id>] [--workspace <id>] [--window <id>] [--index <number>] [--focus <true|false>]
Flags:
​
--surface
string
required
Surface to move (ID, ref, or index)
​
--pane
string
Destination pane (ID, ref, or index)
​
--workspace
string
Destination workspace (ID, ref, or index)
​
--window
string
Destination window (ID, ref, or index)
​
--before
string
Place before this surface
​
--after
string
Place after this surface
​
--index
number
Set specific index position
​
--focus
boolean
Whether to focus the surface after moving
Examples: 
cmux move-surface --surface surface:1 --pane pane:2
Output: 
OK surface=surface:1 pane=pane:2 workspace=workspace:1 window=window:1

​
reorder-surface

Reorder a surface within its pane. 
cmux reorder-surface --surface <id|ref|index> [--before <id>] [--after <id>] [--index <number>]
Flags:
​
--surface
string
required
Surface to reorder (ID, ref, or index)
​
--workspace
string
Workspace context
​
--before
string
Place before this surface
​
--after
string
Place after this surface
​
--index
number
Set specific index position
Examples: 
cmux reorder-surface --surface 2 --before 1
Output: 
OK surface=surface:2 pane=pane:1 workspace=workspace:1

​
surface-health

Check the health status of all surfaces in a workspace. 
cmux surface-health [--workspace <id|ref|index>]
Flags:
​
--workspace
string
Workspace to check (defaults to $CMUX_WORKSPACE_ID)
​
--json
boolean
Output results in JSON format
Output (text): 
surface:1  type=terminal in_window=true
surface:2  type=browser in_window=true
surface:3  type=terminal in_window=false
Output (JSON): 
{
  "surfaces": [
    {
      "ref": "surface:1",
      "type": "terminal",
      "in_window": true
    }
  ]
}

​
trigger-flash

Trigger a visual flash on a surface (for debugging). 
cmux trigger-flash [--workspace <id>] [--surface <id>]
Flags:
​
--workspace
string
Workspace context (defaults to $CMUX_WORKSPACE_ID)
​
--surface
string
Surface to flash (defaults to $CMUX_SURFACE_ID)
Output: 
OK

​
refresh-surfaces

Refresh all surfaces (legacy command). 
cmux refresh-surfaces
Output: 
OK

​
drag-surface-to-split

Drag a surface to create a split in a specific direction (legacy command). 
cmux drag-surface-to-split --surface <id|index> <direction>
Flags:
​
--surface
string
required
Surface to drag (ID or index)
​
--panel
string
Legacy alias for --surface
Arguments:
​
direction
string
required
Split direction: left, right, up, or down
Example: 
cmux drag-surface-to-split --surface 1 right
Output: 
OK

​
Global Flags

These flags can be used with most surface 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