Surface Commands

Manage terminal and browser surfaces (panels) in cmux

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:

Terminal in Current Pane

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:

Current Surface

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:

By Ref

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:

Right Split

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:

To Different Pane

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:

Before Another

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