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

cmux new-workspace --cwd ~/projects/myapp

cmux new-workspace --cwd ~/projects/myapp --command "npm run dev"
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: 
cmux select-workspace --workspace workspace:2

cmux select-workspace --workspace 2

cmux select-workspace --workspace 550e8400-e29b-41d4-a716-446655440000
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: 
cmux close-workspace --workspace workspace:3

cmux close-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: 
cmux rename-workspace My New Title

cmux rename-workspace --workspace workspace:2 Backend API

cmux rename-workspace --workspace 1 -- My Project
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: 
cmux reorder-workspace --workspace 3 --before 1

cmux reorder-workspace --workspace workspace:2 --after workspace:1

cmux reorder-workspace --workspace 3 --index 0
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: 
cmux workspace-action --action next

cmux workspace-action --action previous

cmux workspace-action --action rename --title "New Name"

cmux workspace-action --action rename My New Title
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