Workspace Commands

Manage cmux workspaces (vertical tabs) with CLI commands

Manage workspaces (vertical tabs) in cmux. Each workspace contains one or more panes with surfaces.

list-workspaces

List all workspaces in the current or specified window.

cmux list-workspaces

Flags:

--json · boolean

Output results in JSON format

--id-format · string

Control ID output format: refs, uuids, or both (default: refs)

--window · string

Window ID, ref, or index to list workspaces from

Output (text):

* workspace:1  My Project  [selected]
  workspace:2  Backend
  workspace:3  Frontend

Output (JSON):

{
  "workspaces": [
    {
      "ref": "workspace:1",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "index": 1,
      "title": "My Project",
      "selected": true
    }
  ]
}

new-workspace

Create a new workspace with optional working directory and command.

cmux new-workspace [--cwd <path>] [--command <text>]

Flags:

--cwd · string

Working directory for the new workspace (absolute or relative path)

--command · string

Command to run after workspace creation (automatically appends \n)

Examples:

Basic

cmux new-workspace

Output:

OK workspace:4

select-workspace

Switch to a specific workspace by ID, ref, or index.

cmux select-workspace --workspace <id|ref|index>

Flags:

--workspace · string · required

Workspace ID (UUID), ref (workspace:1), or index (1)

Examples:

By Ref

cmux select-workspace --workspace workspace:2

Output (text):

OK workspace=workspace:2

Output (JSON with —json):

{
  "workspace_ref": "workspace:2",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000"
}

close-workspace

Close a specific workspace by ID, ref, or index.

cmux close-workspace --workspace <id|ref|index>

Flags:

--workspace · string · required

Workspace ID (UUID), ref (workspace:1), or index (1)

Examples:

By Ref

cmux close-workspace --workspace workspace:3

Output:

OK workspace=workspace:3

rename-workspace

Rename a workspace (also aliased as rename-window).

cmux rename-workspace [--workspace <id|ref|index>] [--] <title>

Flags:

--workspace · string

Workspace to rename (defaults to current workspace from $CMUX_WORKSPACE_ID)

Examples:

Current Workspace

cmux rename-workspace My New Title

Output:

OK workspace=workspace:1

current-workspace

Get the ID of the currently selected workspace.

cmux current-workspace

Output (text):

workspace:1

Output (JSON with —json):

{
  "workspace_id": "workspace:1"
}

move-workspace-to-window

Move a workspace to a different window.

cmux move-workspace-to-window --workspace <id|ref|index> --window <id|ref|index>

Flags:

--workspace · string · required

Workspace to move (ID, ref, or index)

--window · string · required

Destination window (ID, ref, or index)

Examples:

cmux move-workspace-to-window --workspace workspace:3 --window window:2

Output:

OK workspace=workspace:3 window=window:2

reorder-workspace

Reorder a workspace within its window.

cmux reorder-workspace --workspace <id|ref|index> [--before <id|ref|index>] [--after <id|ref|index>] [--index <number>]

Flags:

--workspace · string · required

Workspace to reorder (ID, ref, or index)

--window · string

Window context (if omitted, uses current window)

--before · string

Place before this workspace (ID, ref, or index)

--after · string

Place after this workspace (ID, ref, or index)

--index · number

Set specific index position (0-based)

Examples:

Before Another

cmux reorder-workspace --workspace 3 --before 1

Output:

OK workspace=workspace:3 window=window:1 index=0

workspace-action

Perform various workspace actions (next, previous, last, rename).

cmux workspace-action --action <action> [--workspace <id|ref|index>] [--title <text>]

Flags:

--action · string · required

Action: next, previous, last, or rename

--workspace · string

Target workspace (defaults to current workspace)

--title · string

New title (for rename action only)

Examples:

Next Workspace

cmux workspace-action --action next

Output:

OK action=next workspace=workspace:2 window=window:1

Global Flags

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