cmux Cheatsheet

The CLI

Use this cmux reference while you build software engineering projects, review code, or refresh the syntax you reach for most.

Invocation and global options

cmux <path>                       # open a directory as a workspace
cmux [global-options] <command> [options]

cmux <path> goes through the app's file-open path and needs no socket. Every other command talks to the Unix socket.

Global option	Effect
`--socket <path>`	override the socket for this call
`--password <value>`	socket password, beats `CMUX_SOCKET_PASSWORD`
`--json`	machine-readable output where supported
`--id-format <refs\|uuids\|both>`	handle format in output, default `refs`
`--window <id\|ref\|index>`	route through a specific window

--json and --id-format are accepted before or after the command name. The others go before it. The socket defaults to ~/.local/state/cmux/cmux.sock.

cmux --json list-workspaces
cmux list-panes --json --id-format both
cmux --socket /tmp/other.sock ping

Targeting

Every command that acts on something takes a handle in one of three forms: a UUID, a short ref like workspace:2, or a bare index. Inside a cmux terminal the environment supplies defaults, so most calls need no target at all.

cmux identify --json           # what am I attached to
cmux tree --all                # every window, workspace, pane, surface
cmux send --surface surface:3 "make build"
cmux send-key --surface surface:3 enter

Variable	Used as
`CMUX_WORKSPACE_ID`	default `--workspace`
`CMUX_SURFACE_ID`	default `--surface`
`CMUX_TAB_ID`	default `--tab`

Topology commands

cmux list-windows
cmux new-window
cmux focus-window --window window:2
cmux list-workspaces
cmux new-workspace --cwd . --command "npm run dev"
cmux select-workspace --workspace workspace:3
cmux close-workspace --workspace workspace:3
cmux new-split right --focus true
cmux focus-pane --pane pane:2
cmux new-surface --type browser --url http://localhost:3000
cmux move-surface --surface surface:7 --pane pane:2
cmux reorder-workspaces --order workspace:3,workspace:1,workspace:2

reorder-workspace and reorder-workspaces accept --dry-run, and most creation and move commands take --focus <true|false> or --no-focus to say whether the result steals focus. That matters for automation: default to --no-focus so a background script does not yank the person around.

Reading and driving terminals

cmux read-screen --surface surface:3
cmux read-screen --surface surface:3 --scrollback --lines 500
cmux send "git status"
cmux send-key enter
cmux respawn-pane --command "npm run dev"
cmux wait-for build-done --timeout 120
cmux pipe-pane --command "tee /tmp/session.log"
cmux clear-history

There is a layer of tmux-compatible spellings on top of the same primitives: capture-pane, resize-pane, swap-pane, break-pane, join-pane, last-pane, next-window, previous-window, last-window, find-window, set-buffer, list-buffers, paste-buffer, display-message, and set-hook.

Events, RPC, and automation

cmux events --reconnect --name notification.created
cmux events --after 42 --cursor-file ~/.cache/cmux.cursor
cmux capabilities
cmux rpc surface.read_selection '{"surface_id":"..."}'

events streams newline-delimited JSON and is the right primitive for a long-running watcher, with --after <seq> or --cursor-file for resume and --no-ack for a read-only tap. rpc calls a raw socket method when the CLI has no wrapper for it, and capabilities lists what the running build advertises.

Notifications and sidebar metadata are the other half of the automation surface:

cmux notify --title "Deploy finished" --body "staging is live"
cmux set-status tests failing --color '#ef4444'
cmux set-progress 0.75 --label uploading
cmux log --level error "migration rolled back"
cmux jump-to-unread

Browser automation

The embedded browser is scriptable over the same socket, with an API ported from agent-browser.

cmux browser open http://localhost:3000
cmux browser snapshot --interactive
cmux browser click "button.submit"
cmux browser fill "#password" hunter2
cmux browser wait --selector ".dashboard" --timeout-ms 5000
cmux browser get text ".flash"
cmux browser eval "window.localStorage.length"
cmux browser console list
cmux browser errors list
cmux browser screenshot --out /tmp/page.png --json
cmux browser cookies get
cmux browser tab list

snapshot returns an accessibility tree with element refs, which is what makes the click and fill commands usable by an agent that cannot see pixels. --snapshot-after on an action returns the new state in the same call.

Discovery

cmux --help                 # every command, no socket needed
cmux <command> --help       # per-command flags, usually no socket
cmux docs settings          # doc URLs plus curl lines for raw schema
cmux docs api
cmux docs shortcuts
cmux docs browser
cmux docs agents
cmux docs dock
cmux docs sidebars

cmux --help is the authoritative command list for the version you have installed, because the CLI grows fast. Prefer it over any written reference, this one included.