Comprehensive cmux CLI usage guide. Use when the user asks about cmux CLI, cmux --help, socket commands, command discovery, workspaces, panes, surfaces, browser CLI, hooks, feed, settings, or automation through the cmux command.

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: When dogfooding a tagged Debug build from a cmux source checkout, use the tag bound helper instead of /tmp/cmux cli : 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](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.

cmux-cli