Cmux CLI

cmux CLI

Use this skill when a task is best handled through the cmux command line, or when the user asks how to use, inspect, script, or document the cmux CLI. Prefer the live CLI help for exact syntax, then apply the safety rules here.

Prerequisites

Use the cmux binary on PATH for normal user workflows:

cmux --help
cmux version
cmux ping

When dogfooding a tagged Debug build from a cmux source checkout, use the tag-bound helper instead of /tmp/cmux-cli:

CMUX_TAG=<tag> scripts/cmux-debug-cli.sh --help
CMUX_TAG=<tag> scripts/cmux-debug-cli.sh identify --json

scripts/cmux-debug-cli.sh targets /tmp/cmux-debug-<tag>.sock, uses the matching CLI from the tagged app bundle, and scrubs ambient cmux terminal context before running.

Discovery

Always discover current syntax from the CLI before giving exact command help:

cmux --help
cmux help
cmux <command> --help
cmux docs settings
cmux docs shortcuts
cmux docs api
cmux docs browser
cmux docs agents
cmux docs dock

Some subcommands print the top-level help instead of detailed subcommand help. If that happens, search the source locally:

rg -n "Usage: cmux <command>|case \"<command>\"|run.*<Command>" CLI

Do not fetch source files with gh api. Read the local checkout or active worktree.

Mental Model

cmux exposes app state over a Unix socket.

• Window: top-level macOS cmux window.
• Workspace: sidebar tab-like container inside a window.
• Pane: split region inside a workspace.
• Surface: tab inside a pane. A surface can host a terminal, browser, markdown viewer, diff viewer, or other panel.
• Panel: lower-level content implementation. Prefer surface commands unless a command explicitly requires --panel.

Handle inputs usually accept UUIDs, refs such as window:1, workspace:2, pane:3, surface:4, or numeric indexes. Output defaults to refs:

cmux --id-format refs identify
cmux --id-format both list-pane-surfaces --workspace workspace:1
cmux --json --id-format both tree --all

Socket Targeting

Prefer the caller environment when running inside cmux:

printf 'workspace=%s\nsurface=%s\nsocket=%s\n' \
  "${CMUX_WORKSPACE_ID:-}" \
  "${CMUX_SURFACE_ID:-}" \
  "${CMUX_SOCKET_PATH:-}"
cmux identify --json

Use explicit socket targeting for tagged or non-default apps:

cmux --socket /tmp/cmux-debug-<tag>.sock identify --json
CMUX_SOCKET_PATH=/tmp/cmux-debug-<tag>.sock cmux ping

Socket auth resolves in this order: --password, then CMUX_SOCKET_PASSWORD, then the password saved in Settings. Do not ask the user for a password until cmux capabilities --json or the command error shows auth is actually required.

Global Options

Common global options:

cmux --json <command>
cmux --id-format refs <command>
cmux --id-format uuids <command>
cmux --id-format both <command>
cmux --socket <path> <command>
cmux --password <password> <command>

Use --json for automation and scripts. Use plain output when writing quick human-facing status.

Safe First Commands

Start every automation session by inspecting context and capabilities:

cmux ping
cmux capabilities --json
cmux identify --json
cmux list-windows --json
cmux list-workspaces --json
cmux tree --all --json

Inside cmux, scope mutating commands to the caller workspace and surface by default:

cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux read-screen --workspace "${CMUX_WORKSPACE_ID:-}" --surface "${CMUX_SURFACE_ID:-}" --lines 80

Common Workflows

Use references/commands.md for a broader command catalog. High-frequency patterns:

# Open without stealing focus when supported.
cmux open . --focus false
cmux open https://example.com --workspace "${CMUX_WORKSPACE_ID:-}" --focus false

# Create helper output in the caller workspace.
cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false
cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:2 --type terminal --focus false

# Read and write the caller terminal.
cmux read-screen --surface "${CMUX_SURFACE_ID:-}" --scrollback --lines 200
cmux send --surface "${CMUX_SURFACE_ID:-}" "echo ok\n"
cmux send-key --surface "${CMUX_SURFACE_ID:-}" enter

# Browser surface automation.
cmux browser open https://example.com --focus false
cmux browser snapshot --surface surface:5 --compact
cmux browser click "button[type=submit]" --snapshot-after

# Settings and docs.
cmux docs settings
cmux settings path
cmux config validate
cmux reload-config

# Sidebar status for task progress.
cmux set-status build running --workspace "${CMUX_WORKSPACE_ID:-}" --color "#ff9500"
cmux set-progress 0.4 --label "Building" --workspace "${CMUX_WORKSPACE_ID:-}"
cmux clear-status build --workspace "${CMUX_WORKSPACE_ID:-}"
cmux clear-progress --workspace "${CMUX_WORKSPACE_ID:-}"

Command Families

The CLI includes these broad families:

• App/docs/settings: welcome, docs, settings, config, shortcuts, reload-config, themes.
• Openers and viewers: open, markdown, diff, browser commands.
• Context and topology: identify, list-windows, list-workspaces, tree, workspace/window/pane/surface lifecycle commands.
• Terminal IO: read-screen, send, send-key, capture-pane, pipe-pane, clear-history, respawn-pane.
• Browser automation: browser open, goto, snapshot, click, fill, screenshot, get, find, tab, cookies, storage.
• Notifications and sidebar state: notify, notification list/read/clear commands, right-sidebar, set-status, set-progress, log.
• Agent workflows: hooks, feed, claude-teams, codex-teams, omo, omx, omc.
• Auth and cloud: auth, login, logout, vm or cloud.
• Advanced socket/debug: capabilities, events, rpc, surface-health, debug-terminals, trigger-flash.
• tmux compatibility: capture-pane, resize-pane, wait-for, swap-pane, break-pane, join-pane, find-window, buffers, hooks, messages.

Non-Disruptive Automation

The user may be looking at a different workspace, window, or app. Treat focus changes like UI clicks.

Do not call these unless the user explicitly asks:

• focus-window
• focus-pane
• focus-panel
• select-workspace
• tab-action actions that focus or select
• right-sidebar focus

Prefer additive, scoped commands:

cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false
cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:2 --type terminal --focus false
cmux send --workspace "${CMUX_WORKSPACE_ID:-}" --surface surface:7 "npm test\n"

When creating helper output for a task, reuse one right-side helper pane in the caller workspace. Use list-panes and list-pane-surfaces first, then create a new pane only when no suitable helper pane exists.

Settings Boundary

cmux-owned settings live in ~/.config/cmux/cmux.json. Ghostty terminal behavior lives in ~/.config/ghostty/config. Prefer Ghostty config for terminal behavior Ghostty already supports, such as font, cursor style, scrollback, theme, background opacity, and blur.

Before editing cmux.json, run:

cmux docs settings
cmux settings path

Back up the existing file to a timestamped .bak copy before editing, then run:

cmux reload-config

Debug and Tagged Builds

For cmux app/runtime development, build a tagged app before using CLI commands against it:

./scripts/reload.sh --tag <tag>
CMUX_TAG=<tag> scripts/cmux-debug-cli.sh identify --json
CMUX_TAG=<tag> scripts/cmux-debug-cli.sh list-workspaces --json

Do not use bare xcodebuild without a tagged -derivedDataPath. Do not use /tmp/cmux-cli for tagged dogfood because it points at the most recently reloaded build and can target the wrong socket.