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 --helpcmux versioncmux 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 --helpCMUX_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 --helpcmux helpcmux <command> --helpcmux docs settingscmux docs shortcutscmux docs apicmux docs browsercmux docs agentscmux 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 identifycmux --id-format both list-pane-surfaces --workspace workspace:1cmux --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 --jsonCMUX_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 pingcmux capabilities --jsoncmux identify --jsoncmux list-windows --jsoncmux list-workspaces --jsoncmux tree --all --json

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

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

Common Workflows

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

# Open without stealing focus when supported.cmux open . --focus falsecmux 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 falsecmux 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 200cmux 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 falsecmux browser snapshot --surface surface:5 --compactcmux browser click "button[type=submit]" --snapshot-after
# Settings and docs.cmux docs settingscmux settings pathcmux config validatecmux 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 falsecmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" --pane pane:2 --type terminal --focus falsecmux 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 settingscmux 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 --jsonCMUX_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.

Useful debug files:

cat /tmp/cmux-last-cli-pathcat /tmp/cmux-last-debug-log-pathtail -f "$(cat /tmp/cmux-last-debug-log-path 2>/dev/null || echo /tmp/cmux-debug.log)"

Rules

• Run cmux --help or cmux <command> --help before giving exact syntax.
• Use --json for scripts and agent automation.
• Scope mutating commands with --workspace, --surface, --pane, and --window where available.
• Prefer CMUX_WORKSPACE_ID, CMUX_SURFACE_ID, and CMUX_SOCKET_PATH over focused-window fallbacks.
• Pass --focus false or --no-focus whenever the command supports it unless the user asked to focus something.
• Never change settings without first running cmux docs settings or cmux settings path; back up cmux.json before editing.
• Prefer Ghostty config for terminal behavior Ghostty already supports.
• For tagged Debug builds, use CMUX_TAG=<tag> scripts/cmux-debug-cli.sh ....
• Do not run commands against the default socket when the task is about a tagged app.
• Do not ask the user to paste commands into cmux when the CLI can perform the setup directly.

Related Skills

• skills/cmux/SKILL.md covers core topology and routing.
• the cmux-workspace skill covers current-workspace targeting and helper panes.
• the cmux-browser skill covers browser surface automation.
• the cmux-config skill covers safe settings edits.
• the cmux-markdown skill covers markdown viewer panels.