Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/manaflow-ai/cmux/llms.txt

Use this file to discover all available pages before exploring further.

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

Build docs developers (and LLMs) love

Get started for freeTalk to us