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.

Useful debug files:

cat /tmp/cmux-last-cli-path
cat /tmp/cmux-last-debug-log-path
tail -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.

cmux CLI (Codex agent instructions)

When asked to use or explain the cmux CLI, read the cmux-cli skill first.

Role

Use live CLI help and local source to verify syntax, then run the smallest scoped command that satisfies the task.

Checklist

1. Check cmux --help or cmux <command> --help before presenting exact syntax. 2. Target the caller workspace and surface unless the user names another target. 3. Use --json for automation. 4. Avoid focus-changing commands unless explicitly requested.

Output

Report the command run, the relevant result, and any remaining command the user should run manually only when the CLI cannot safely do it for them.

cmux CLI Command Examples

Run cmux --help first for the current full command list. These examples show common shapes and safe defaults.

Open

cmux <path>
cmux open <path-or-url>...
cmux open . --focus false
cmux open https://example.com --workspace "${CMUX_WORKSPACE_ID:-}" --focus false

Windows and Workspaces

cmux list-windows --json
cmux current-window --json
cmux new-window
cmux focus-window --window window:1
cmux close-window --window window:2
cmux list-workspaces --window window:1 --json
cmux current-workspace --json
cmux new-workspace --name "debug auth" --cwd "$PWD" --focus false
cmux rename-workspace --workspace workspace:2 "build logs"
cmux close-workspace --workspace workspace:2
cmux reorder-workspace --workspace workspace:3 --before workspace:1 --dry-run
cmux move-workspace-to-window --workspace workspace:3 --window window:2

Panes and Surfaces

cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json
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 move-surface --surface surface:4 --pane pane:2 --focus false
cmux reorder-surface --surface surface:4 --before surface:2 --focus false
cmux split-off --surface surface:4 right --focus false
cmux close-surface --surface surface:4

Terminal IO

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
cmux capture-pane --surface "${CMUX_SURFACE_ID:-}" --scrollback --lines 200
cmux clear-history --surface "${CMUX_SURFACE_ID:-}"
cmux respawn-pane --surface surface:4 --command "npm test"

Browser

cmux browser status
cmux browser open https://example.com --focus false
cmux browser identify --surface surface:5
cmux browser snapshot --surface surface:5 --compact
cmux browser click "button[type=submit]" --snapshot-after
cmux browser fill "input[name=email]" "person@example.com"
cmux browser screenshot --out /tmp/cmux-browser.png --json

Use the cmux-browser skill for detailed browser automation rules.

Markdown and Diffs

cmux markdown open README.md --focus false
cmux diff --source unstaged --cwd "$PWD" --focus false
git diff | cmux diff - --focus false

Notifications and Sidebar State

cmux notify --title "Build finished" --body "All checks passed" --workspace "${CMUX_WORKSPACE_ID:-}"
cmux list-notifications --json
cmux mark-notification-read --workspace "${CMUX_WORKSPACE_ID:-}"
cmux clear-notifications --workspace "${CMUX_WORKSPACE_ID:-}"
cmux set-status build running --workspace "${CMUX_WORKSPACE_ID:-}" --color "#ff9500"
cmux set-progress 0.4 --label "Building" --workspace "${CMUX_WORKSPACE_ID:-}"
cmux log --workspace "${CMUX_WORKSPACE_ID:-}" --level info -- "Started build"
cmux sidebar-state --workspace "${CMUX_WORKSPACE_ID:-}" --json
cmux clear-status build --workspace "${CMUX_WORKSPACE_ID:-}"
cmux clear-progress --workspace "${CMUX_WORKSPACE_ID:-}"

Right Sidebar

cmux right-sidebar show --workspace "${CMUX_WORKSPACE_ID:-}" --no-focus
cmux right-sidebar mode feed --workspace "${CMUX_WORKSPACE_ID:-}" --no-focus
cmux right-sidebar hide --workspace "${CMUX_WORKSPACE_ID:-}" --no-focus

Settings and Config

cmux docs settings
cmux settings path
cmux config paths
cmux config doctor
cmux config validate
cmux reload-config
cmux shortcuts

Themes

cmux themes list
cmux themes set <theme-name>
cmux themes clear

Authentication and Cloud VMs

cmux auth status
cmux login
cmux logout
cmux vm ls
cmux vm new
cmux vm shell <vm-id>
cmux vm exec <vm-id> -- <command>
cmux vm ssh <vm-id>
cmux vm rm <vm-id>

Agent Hooks, Teams, and Feed

cmux hooks setup
cmux hooks setup --agent codex
cmux hooks uninstall --agent claude
cmux hooks <agent> install
cmux hooks <agent> uninstall
cmux hooks feed --source codex --event Stop
cmux feed tui
cmux feed clear
cmux claude-teams
cmux codex-teams
cmux omo
cmux omx
cmux omc

Events and RPC

cmux events --after 0 --limit 50 --json
cmux events --name workspace.created --reconnect
cmux rpc <method> '{"key":"value"}'

tmux Compatibility

cmux capture-pane --surface surface:4 --scrollback --lines 200
cmux resize-pane --pane pane:2 -R --amount 10
cmux pipe-pane --surface surface:4 --command "cat > /tmp/pane.log"
cmux wait-for -S build-done
cmux wait-for build-done --timeout 30
cmux swap-pane --pane pane:2 --target-pane pane:3 --focus false
cmux break-pane --surface surface:4 --focus false
cmux join-pane --target-pane pane:2 --surface surface:4 --focus false
cmux find-window --content --select "server ready"
cmux set-buffer --name scratch "hello"
cmux paste-buffer --name scratch --surface surface:4
cmux display-message --print "workspace=#{workspace_id}"