AutomationCLI Reference
Automation

CLI Reference

cmux provides both a CLI tool and a Unix socket for programmatic control. Every command is available through both interfaces.

Socket

BuildPath
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

ModeDescriptionHow to enable
OffSocket disabledSettings UI or CMUX_SOCKET_MODE=off
cmux processes onlyOnly processes spawned inside cmux terminals can connect.Default mode in Settings UI
allowAllAllow 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

FlagDescription
--socket PATHCustom socket path
--jsonOutput in JSON format
--window IDTarget a specific window
--workspace IDTarget a specific workspace
--surface IDTarget a specific surface
--id-format refs|uuids|bothControl identifier format in JSON output

Workspace commands

list-workspaces

List all open workspaces.

CLI
cmux list-workspaces
cmux list-workspaces --json
Socket
{"id":"ws-list","method":"workspace.list","params":{}}

new-workspace

Create a new workspace.

CLI
cmux new-workspace
Socket
{"id":"ws-new","method":"workspace.create","params":{}}

select-workspace

Switch to a specific workspace.

CLI
cmux select-workspace --workspace <id