Automation
CLI Reference
cmux provides both a CLI tool and a Unix socket for programmatic control. Every command is available through both interfaces.
Socket
| Build | Path |
|---|---|
| Release | /tmp/cmux.sock |
| Debug | /tmp/cmux-debug.sock |
| Tagged debug build | /tmp/cmux-debug-<tag>.sock |
Override with the CMUX_SOCKET_PATH environment variable. Send one newline-terminated JSON request per call:
{"id":"req-1","method":"workspace.list","params":{}}
// Response:
{"id":"req-1","ok":true,"result":{"workspaces":[...]}}JSON socket requests must use method and params. Legacy v1 JSON payloads such as
{"command":"..."} are not supported.Access modes
| Mode | Description | How to enable |
|---|---|---|
| Off | Socket disabled | Settings UI or CMUX_SOCKET_MODE=off |
| cmux processes only | Only processes spawned inside cmux terminals can connect. | Default mode in Settings UI |
| allowAll | Allow any local process to connect (no ancestry check). | Environment override only: CMUX_SOCKET_MODE=allowAll |
On shared machines, use Off or cmux processes only.
CLI options
| Flag | Description |
|---|---|
--socket PATH | Custom socket path |
--json | Output in JSON format |
--window ID | Target a specific window |
--workspace ID | Target a specific workspace |
--surface ID | Target a specific surface |
--id-format refs|uuids|both | Control identifier format in JSON output |
Workspace commands
list-workspaces
List all open workspaces.
CLI
cmux list-workspaces
cmux list-workspaces --jsonSocket
{"id":"ws-list","method":"workspace.list","params":{}}new-workspace
Create a new workspace.
CLI
cmux new-workspaceSocket
{"id":"ws-new","method":"workspace.create","params":{}}select-workspace
Switch to a specific workspace.
CLI
cmux select-workspace --workspace <id