cmux-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

当某项任务最适合通过

cmux

命令行处理，或者用户询问如何使用、检查、编写脚本或记录cmux CLI时，使用此技能。优先使用实时CLI帮助获取准确语法，然后应用此处的安全规则。

Prerequisites

前提条件

Use the

cmux

binary on

PATH

for normal user workflows:

bash

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

bash

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.

在常规用户工作流中，使用

PATH

中的

cmux

二进制文件：

bash

cmux --help
cmux version
cmux ping

当从cmux源码检出中试用带标签的Debug构建版本时，请使用绑定标签的辅助脚本，而非

/tmp/cmux-cli

：

bash

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

scripts/cmux-debug-cli.sh

指向

/tmp/cmux-debug-<tag>.sock

，使用标签对应的应用包中的匹配CLI，并在运行前清除环境中的cmux终端上下文。

Discovery

命令发现

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

bash

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:

bash

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.

在提供准确命令帮助前，务必从CLI中发现当前语法：

bash

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

部分子命令会打印顶层帮助而非详细的子命令帮助。如果出现这种情况，在本地源码中搜索：

bash

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

不要使用

gh api

获取源文件。读取本地检出的代码或活动工作树。

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:

bash

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

cmux通过Unix socket暴露应用状态。

Window：macOS cmux的顶层窗口。
Workspace：窗口内类似侧边栏标签的容器。
Pane：工作区内的拆分区域。
Surface：窗格内的标签页。一个Surface可以承载终端、浏览器、markdown查看器、差异查看器或其他面板。
Panel：底层内容实现。除非命令明确要求
```
--panel
```
，否则优先使用surface命令。

输入通常接受UUID、引用（如

window:1

、

workspace:2

、

pane:3

、

surface:4

）或数字索引。输出默认使用引用：

bash

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

Socket Targeting

Socket 目标定位

Prefer the caller environment when running inside cmux:

bash

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:

bash

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.

在cmux内部运行时，优先调用者环境：

bash

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

对带标签或非默认应用使用显式socket定位：

bash

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

Socket认证的优先级为：

--password

，然后是

CMUX_SOCKET_PASSWORD

，最后是设置中保存的密码。除非

cmux capabilities --json

或命令错误显示确实需要认证，否则不要向用户索要密码。

Global Options

全局选项

Common global options:

bash

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.

常见全局选项：

bash

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>

自动化和脚本使用

--json

。编写面向人类的快速状态时使用纯文本输出。

Safe First Commands

安全初始命令

Start every automation session by inspecting context and capabilities:

bash

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:

bash

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

每个自动化会话都应从检查上下文和功能开始：

bash

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

在cmux内部，默认将修改命令限定在调用者的工作区和界面：

bash

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:

bash

undefined

使用references/commands.md获取更全面的命令目录。高频模式：

bash

undefined

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:-}"

undefined

undefined

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.

CLI包含以下广泛的命令族：

应用/文档/设置：

welcome

、

docs

、

settings

、

config

、

shortcuts

、

reload-config

、

themes

。

打开器和查看器：
```
open
```
、
```
markdown
```
、
```
diff
```
、浏览器命令。
上下文和拓扑：
```
identify
```
、
```
list-windows
```
、
```
list-workspaces
```
、
```
tree
```
、工作区/窗口/窗格/界面生命周期命令。

终端IO：

read-screen

、

send

、

send-key

、

capture-pane

、

pipe-pane

、

clear-history

、

respawn-pane

。

浏览器自动化：
```
browser open
```
、
```
goto
```
、
```
snapshot
```
、
```
click
```
、
```
fill
```
、
```
screenshot
```
、
```
get
```
、
```
find
```
、
```
tab
```
、cookies、storage。
通知和侧边栏状态：
```
notify
```
、通知列表/读取/清除命令、
```
right-sidebar
```
、
```
set-status
```
、
```
set-progress
```
、
```
log
```
。

Agent工作流：

hooks

、

feed

、

claude-teams

、

codex-teams

、

omo

、

omx

、

omc

。

认证和云：
```
auth
```
、
```
login
```
、
```
logout
```
、
```
vm
```
或
```
cloud
```
。

高级socket/调试：

capabilities

、

events

、

rpc

、

surface-health

、

debug-terminals

、

trigger-flash

。

tmux兼容性：

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:

bash

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.

用户可能正在查看不同的工作区、窗口或应用。将焦点更改视为UI点击操作。

除非用户明确要求，否则不要调用以下命令：

```
focus-window
```
```
focus-pane
```
```
focus-panel
```
```
select-workspace
```
会获取焦点或进行选择的
```
tab-action
```
操作
```
right-sidebar focus
```

优先使用附加的、限定范围的命令：

bash

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"

为任务创建辅助输出时，在调用者工作区重用一个右侧辅助窗格。先使用

list-panes

和

list-pane-surfaces

，仅当没有合适的辅助窗格时才创建新窗格。

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:

bash

cmux docs settings
cmux settings path

Back up the existing file to a timestamped

.bak

copy before editing, then run:

bash

cmux reload-config

cmux自有设置存储在

~/.config/cmux/cmux.json

中。Ghostty终端行为设置存储在

~/.config/ghostty/config

中。对于Ghostty已支持的终端行为（如字体、光标样式、回滚、主题、背景透明度和模糊），优先使用Ghostty配置。

编辑

cmux.json

前，运行：

bash

cmux docs settings
cmux settings path

编辑前将现有文件备份到带时间戳的

.bak

副本，然后运行：

bash

cmux reload-config

Debug and Tagged Builds

调试和带标签构建

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

bash

./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:

bash

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)"

对于cmux应用/运行时开发，在使用CLI命令之前先构建带标签的应用：

bash

./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

不要使用不带标签

-derivedDataPath

的裸

xcodebuild

。不要将

/tmp/cmux-cli

用于带标签的试用版本，因为它指向最近重新加载的构建，可能会定位到错误的socket。

有用的调试文件：

bash

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.

在提供准确语法前，运行
```
cmux --help
```
或
```
cmux <command> --help
```
。
脚本和Agent自动化使用
```
--json
```
。
尽可能使用
```
--workspace
```
、
```
--surface
```
、
```
--pane
```
和
```
--window
```
限定修改命令的范围。
优先使用
```
CMUX_WORKSPACE_ID
```
、
```
CMUX_SURFACE_ID
```
和
```
CMUX_SOCKET_PATH
```
，而非聚焦窗口的回退选项。
只要命令支持，就传递
```
--focus false
```
或
```
--no-focus
```
，除非用户要求获取焦点。
在运行
```
cmux docs settings
```
或
```
cmux settings path
```
前，不要更改设置；编辑前备份
```
cmux.json
```
。
对于Ghostty已支持的终端行为，优先使用Ghostty配置。

对于带标签的Debug构建，使用

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

。

当任务涉及带标签的应用时，不要针对默认socket运行命令。
当CLI可以直接执行设置时，不要要求用户将命令粘贴到cmux中。

cmux-cli

Original

Translation

cmux CLI

cmux CLI

Prerequisites

前提条件

Discovery

命令发现

Mental Model

心智模型

Socket Targeting

Socket 目标定位

Global Options

全局选项

Safe First Commands

安全初始命令

Common Workflows

常见工作流

Open without stealing focus when supported.

支持时，打开但不获取焦点。

Create helper output in the caller workspace.

在调用者工作区创建辅助输出。

Read and write the caller terminal.

读取和写入调用者终端。

Browser surface automation.

浏览器界面自动化。

Settings and docs.

设置和文档。

Sidebar status for task progress.

侧边栏任务进度状态。

Command Families

命令族

Non-Disruptive Automation

无干扰自动化

Settings Boundary

设置边界

Debug and Tagged Builds

调试和带标签构建

Rules

规则

Related Skills

相关技能