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=<

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:

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

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:

Socket Targeting

Prefer the caller environment when running inside cmux:

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

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:

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:

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

Common Workflows

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

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:

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:

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

Debug and Tagged Builds

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

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:

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.