Back to Details

cmux

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
This skill provides complete knowledge of the 
cmux
CLI so you can control the cmux terminal multiplexer without needing to rediscover its interface.
本技能提供了完整的
cmux
CLI相关知识，让你无需重新摸索其接口即可控制cmux终端复用器。

Binary Location

二进制文件位置

/Applications/cmux.app/Contents/Resources/bin/cmux
Usually on PATH as 
cmux
.
/Applications/cmux.app/Contents/Resources/bin/cmux
通常在PATH中可直接使用
cmux
调用。

Global Options

全局选项

cmux [--socket PATH] [--window WINDOW] [--password PASSWORD] [--json] [--id-format refs|uuids|both] [--version] <command> [options]
  • --json
    : Output JSON (use this when you need to parse results programmatically)
  • --id-format refs|uuids|both
    : Control ID format in output (defaults to refs)
  • --socket PATH
    : Override Unix socket path
  • --password PASSWORD
    : Socket auth password
cmux [--socket PATH] [--window WINDOW] [--password PASSWORD] [--json] [--id-format refs|uuids|both] [--version] <command> [options]
  • --json
    ：输出JSON格式结果（当你需要通过程序解析结果时使用）
  • --id-format refs|uuids|both
    ：控制输出中的ID格式（默认是refs）
  • --socket PATH
    ：覆盖Unix套接字路径
  • --password PASSWORD
    ：套接字认证密码

Environment Variables

环境变量

  • CMUX_WORKSPACE_ID
    - Auto-set in cmux terminals. Default 
    --workspace
    for all commands.
  • CMUX_TAB_ID
    - Optional alias for 
    tab-action
    /
    rename-tab
    default 
    --tab
    .
  • CMUX_SURFACE_ID
    - Auto-set in cmux terminals. Default 
    --surface
    .
  • CMUX_SOCKET_PATH
    - Override the default Unix socket path (
    /tmp/cmux.sock
    ).
Important: Because 
CMUX_WORKSPACE_ID
and 
CMUX_SURFACE_ID
are auto-set, most commands work without explicit 
--workspace
/
--surface
flags when run from within a cmux terminal. They default to the caller's context.
  • CMUX_WORKSPACE_ID
    - 在cmux终端中自动设置，所有命令的默认
    --workspace
    参数值
  • CMUX_TAB_ID
    - 可选别名，用于
    tab-action
    /
    rename-tab
    命令的默认
    --tab
    参数
  • CMUX_SURFACE_ID
    - 在cmux终端中自动设置，默认
    --surface
    参数值
  • CMUX_SOCKET_PATH
    - 覆盖默认Unix套接字路径（
    /tmp/cmux.sock
    ）
重要提示：由于
CMUX_WORKSPACE_ID
和
CMUX_SURFACE_ID
是自动设置的，在cmux终端内运行大多数命令时无需显式指定
--workspace
/
--surface
参数，会默认使用调用者的上下文。

ID/Ref System

ID/引用系统

Most commands accept IDs in these formats:
  • UUIDs: Full unique identifiers
  • Short refs: 
    window:1
    , 
    workspace:2
    , 
    pane:3
    , 
    surface:4
  • Indexes: Numeric indexes
tab-action
also accepts 
tab:<n>
in addition to 
surface:<n>
.
大多数命令接受以下格式的ID：
  • UUIDs：完整的唯一标识符
  • 短引用：
    window:1
    、
    workspace:2
    、
    pane:3
    、
    surface:4
  • 索引：数字索引
tab-action
除了
surface:<n>
之外还接受
tab:<n>
格式。

Commands Reference

命令参考

Discovery & Status

发现与状态

CommandDescription
version
Show cmux version
ping
Check if cmux is running
capabilities
List supported capabilities
identify [--workspace] [--surface] [--no-caller]
Identify current context
CommandDescription
version
显示cmux版本
ping
检查cmux是否正在运行
capabilities
列出支持的功能
identify [--workspace] [--surface] [--no-caller]
识别当前上下文

Windows

窗口

CommandDescription
list-windows
List all windows
current-window
Get the current window
new-window
Create a new window
focus-window --window <id>
Focus a window
close-window --window <id>
Close a window
rename-window [--workspace] <title>
Rename a window
next-window
/ 
previous-window
/ 
last-window
Navigate windows
CommandDescription
list-windows
列出所有窗口
current-window
获取当前窗口
new-window
创建新窗口
focus-window --window <id>
聚焦到指定窗口
close-window --window <id>
关闭指定窗口
rename-window [--workspace] <title>
重命名窗口
next-window
/ 
previous-window
/ 
last-window
窗口导航

Workspaces (tabs in the UI)

工作区（UI中的标签页）

CommandDescription
list-workspaces
List all workspaces
current-workspace
Get current workspace
new-workspace [--command <text>]
Create workspace, optionally run a command
select-workspace --workspace <id|ref>
Switch to workspace
close-workspace --workspace <id|ref>
Close workspace
rename-workspace [--workspace] <title>
Rename workspace
workspace-action --action <name> [--workspace] [--title]
Trigger workspace action
move-workspace-to-window --workspace <id|ref> --window <id|ref>
Move workspace to another window
reorder-workspace --workspace <id|ref|index> (--index <n> | --before <id> | --after <id>) [--window]
Reorder workspace
CommandDescription
list-workspaces
列出所有工作区
current-workspace
获取当前工作区
new-workspace [--command <text>]
创建工作区，可选运行指定命令
select-workspace --workspace <id|ref>
切换到指定工作区
close-workspace --workspace <id|ref>
关闭指定工作区
rename-workspace [--workspace] <title>
重命名工作区
workspace-action --action <name> [--workspace] [--title]
触发工作区动作
move-workspace-to-window --workspace <id|ref> --window <id|ref>
将工作区移动到其他窗口
reorder-workspace --workspace <id|ref|index> (--index <n> | --before <id> | --after <id>) [--window]
重排工作区顺序

Panes & Surfaces

窗格与表层

CommandDescription
list-panes [--workspace]
List panes in workspace
list-pane-surfaces [--workspace] [--pane]
List surfaces in a pane
focus-pane --pane <id|ref> [--workspace]
Focus a pane
new-pane [--type terminal|browser] [--direction left|right|up|down] [--workspace] [--url]
Create a new pane
new-split <left|right|up|down> [--workspace] [--surface] [--panel]
Split current pane
new-surface [--type terminal|browser] [--pane] [--workspace] [--url]
Add surface (tab) to pane
close-surface [--surface] [--workspace]
Close a surface
move-surface --surface <id> [--pane] [--workspace] [--window] [--before] [--after] [--index] [--focus]
Move surface between panes
reorder-surface --surface <id> (--index <n> | --before <id> | --after <id>)
Reorder surface within pane
drag-surface-to-split --surface <id|ref> <left|right|up|down>
Drag surface into a new split
resize-pane --pane <id|ref> [--workspace] (-L|-R|-U|-D) [--amount <n>]
Resize pane
swap-pane --pane <id|ref> --target-pane <id|ref> [--workspace]
Swap two panes
break-pane [--workspace] [--pane] [--surface] [--no-focus]
Break pane into new workspace
join-pane --target-pane <id|ref> [--workspace] [--pane] [--surface] [--no-focus]
Join pane into another
last-pane [--workspace]
Focus previous pane
refresh-surfaces
Refresh all surfaces
surface-health [--workspace]
Check surface health
respawn-pane [--workspace] [--surface] [--command <cmd>]
Respawn a pane
CommandDescription
list-panes [--workspace]
列出工作区中的所有窗格
list-pane-surfaces [--workspace] [--pane]
列出指定窗格中的所有表层
focus-pane --pane <id|ref> [--workspace]
聚焦到指定窗格
new-pane [--type terminal|browser] [--direction left|right|up|down] [--workspace] [--url]
创建新窗格
new-split <left|right|up|down> [--workspace] [--surface] [--panel]
拆分当前窗格
new-surface [--type terminal|browser] [--pane] [--workspace] [--url]
向窗格添加表层（标签页）
close-surface [--surface] [--workspace]
关闭指定表层
move-surface --surface <id> [--pane] [--workspace] [--window] [--before] [--after] [--index] [--focus]
在窗格之间移动表层
reorder-surface --surface <id> (--index <n> | --before <id> | --after <id>)
在窗格内重排表层顺序
drag-surface-to-split --surface <id|ref> <left|right|up|down>
将表层拖动到新分屏
resize-pane --pane <id|ref> [--workspace] (-L|-R|-U|-D) [--amount <n>]
调整窗格大小
swap-pane --pane <id|ref> --target-pane <id|ref> [--workspace]
交换两个窗格
break-pane [--workspace] [--pane] [--surface] [--no-focus]
将窗格拆分到新工作区
join-pane --target-pane <id|ref> [--workspace] [--pane] [--surface] [--no-focus]
将窗格合并到另一个窗格
last-pane [--workspace]
聚焦到上一个窗格
refresh-surfaces
刷新所有表层
surface-health [--workspace]
检查表层健康状态
respawn-pane [--workspace] [--surface] [--command <cmd>]
重启窗格

Tabs (Surface-level)

标签页（表层级别）

CommandDescription
tab-action --action <name> [--tab] [--surface] [--workspace] [--title] [--url]
Trigger tab action
rename-tab [--workspace] [--tab] [--surface] <title>
Rename a tab
trigger-flash [--workspace] [--surface]
Flash a surface
CommandDescription
tab-action --action <name> [--tab] [--surface] [--workspace] [--title] [--url]
触发标签页动作
rename-tab [--workspace] [--tab] [--surface] <title>
重命名标签页
trigger-flash [--workspace] [--surface]
闪烁指定表层

Panels

面板

CommandDescription
list-panels [--workspace]
List panels
focus-panel --panel <id|ref> [--workspace]
Focus a panel
send-panel --panel <id|ref> [--workspace] <text>
Send text to panel
send-key-panel --panel <id|ref> [--workspace] <key>
Send keypress to panel
CommandDescription
list-panels [--workspace]
列表面板
focus-panel --panel <id|ref> [--workspace]
聚焦到指定面板
send-panel --panel <id|ref> [--workspace] <text>
向面板发送文本
send-key-panel --panel <id|ref> [--workspace] <key>
向面板发送按键

Reading & Sending to Terminals

终端内容读取与指令发送

CommandDescription
read-screen [--workspace] [--surface] [--scrollback] [--lines <n>]
Read terminal screen content
capture-pane [--workspace] [--surface] [--scrollback] [--lines <n>]
Alias for read-screen
send [--workspace] [--surface] <text>
Send text to a terminal
send-key [--workspace] [--surface] <key>
Send a keypress to a terminal
pipe-pane --command <shell-command> [--workspace] [--surface]
Pipe pane output to a command
clear-history [--workspace] [--surface]
Clear scrollback history
find-window [--content] [--select] <query>
Find window by content or title
CommandDescription
read-screen [--workspace] [--surface] [--scrollback] [--lines <n>]
读取终端屏幕内容
capture-pane [--workspace] [--surface] [--scrollback] [--lines <n>]
read-screen的别名
send [--workspace] [--surface] <text>
向终端发送文本
send-key [--workspace] [--surface] <key>
向终端发送按键
pipe-pane --command <shell-command> [--workspace] [--surface]
将窗格输出管道到指定命令
clear-history [--workspace] [--surface]
清除回滚历史
find-window [--content] [--select] <query>
按内容或标题查找窗口

Clipboard / Buffers

剪贴板/缓冲区

CommandDescription
set-buffer [--name <name>] <text>
Store text in a named buffer
list-buffers
List all buffers
paste-buffer [--name <name>] [--workspace] [--surface]
Paste buffer into surface
CommandDescription
set-buffer [--name <name>] <text>
将文本存储到命名缓冲区
list-buffers
列出所有缓冲区
paste-buffer [--name <name>] [--workspace] [--surface]
将缓冲区内容粘贴到表层

Notifications

通知

CommandDescription
notify --title <text> [--subtitle <text>] [--body <text>] [--workspace] [--surface]
Send a notification
list-notifications
List notifications
clear-notifications
Clear notifications
CommandDescription
notify --title <text> [--subtitle <text>] [--body <text>] [--workspace] [--surface]
发送通知
list-notifications
列出通知
clear-notifications
清除通知

Sidebar Metadata

侧边栏元数据

CommandDescription
set-status <key> <value> [--icon <name>] [--color <#hex>] [--workspace]
Set sidebar status
clear-status <key> [--workspace]
Clear a status key
list-status [--workspace]
List all status entries
set-progress <0.0-1.0> [--label <text>] [--workspace]
Set progress bar
clear-progress [--workspace]
Clear progress bar
log [--level <level>] [--source <name>] [--workspace] [--] <message>
Write to sidebar log
clear-log [--workspace]
Clear sidebar log
list-log [--limit <n>] [--workspace]
List log entries
sidebar-state [--workspace]
Get sidebar state
CommandDescription
set-status <key> <value> [--icon <name>] [--color <#hex>] [--workspace]
设置侧边栏状态
clear-status <key> [--workspace]
清除指定状态键
list-status [--workspace]
列出所有状态条目
set-progress <0.0-1.0> [--label <text>] [--workspace]
设置进度条
clear-progress [--workspace]
清除进度条
log [--level <level>] [--source <name>] [--workspace] [--] <message>
写入侧边栏日志
clear-log [--workspace]
清除侧边栏日志
list-log [--limit <n>] [--workspace]
列出日志条目
sidebar-state [--workspace]
获取侧边栏状态

Browser Control

浏览器控制

Create and control browser panes within cmux.
Opening browsers:
cmux browser open [url]              # Open browser in caller's workspace
cmux browser open-split [url]        # Open as a split
cmux new-pane --type browser [--url <url>] [--direction left|right|up|down]
Navigation:
cmux browser goto|navigate <url> [--snapshot-after]
cmux browser back|forward|reload [--snapshot-after]
cmux browser url|get-url
Reading page content:
cmux browser snapshot [--interactive|-i] [--cursor] [--compact] [--max-depth <n>] [--selector <css>]
cmux browser get <url|title|text|html|value|attr|count|box|styles> [...]
cmux browser console <list|clear>
cmux browser errors <list|clear>
Interacting with elements:
cmux browser click|dblclick|hover|focus|check|uncheck|scroll-into-view <selector> [--snapshot-after]
cmux browser type <selector> <text> [--snapshot-after]
cmux browser fill <selector> [text] [--snapshot-after]    # empty text clears input
cmux browser press|keydown|keyup <key> [--snapshot-after]
cmux browser select <selector> <value> [--snapshot-after]
cmux browser scroll [--selector <css>] [--dx <n>] [--dy <n>] [--snapshot-after]
Querying elements:
cmux browser is <visible|enabled|checked> <selector>
cmux browser find <role|text|label|placeholder|alt|title|testid|first|last|nth> ...
cmux browser highlight <selector>
Waiting:
cmux browser wait [--selector <css>] [--text <text>] [--url-contains <text>] [--load-state <interactive|complete>] [--function <js>] [--timeout-ms <ms>]
JavaScript execution:
cmux browser eval <script>
Page manipulation:
cmux browser frame <selector|main>
cmux browser dialog <accept|dismiss> [text]
cmux browser viewport <width> <height>
cmux browser geolocation|geo <lat> <lon>
cmux browser offline <true|false>
cmux browser addscript <script>
cmux browser addstyle <css>
cmux browser addinitscript <script>
State & network:
cmux browser state <save|load> <path>
cmux browser cookies <get|set|clear> [...]
cmux browser storage <local|session> <get|set|clear> [...]
cmux browser download [wait] [--path <path>] [--timeout-ms <ms>]
cmux browser network <route|unroute|requests> [...]
cmux browser trace <start|stop> [path]
cmux browser screencast <start|stop>
cmux browser input <mouse|keyboard|touch>
Browser tabs:
cmux browser tab <new|list|switch|close|<index>> [...]
Browser identity:
cmux browser identify [--surface <id|ref|index>]
在cmux中创建和控制浏览器窗格。
打开浏览器：
cmux browser open [url]              # 在调用者的工作区打开浏览器
cmux browser open-split [url]        # 作为分屏打开
cmux new-pane --type browser [--url <url>] [--direction left|right|up|down]
导航：
cmux browser goto|navigate <url> [--snapshot-after]
cmux browser back|forward|reload [--snapshot-after]
cmux browser url|get-url
读取页面内容：
cmux browser snapshot [--interactive|-i] [--cursor] [--compact] [--max-depth <n>] [--selector <css>]
cmux browser get <url|title|text|html|value|attr|count|box|styles> [...]
cmux browser console <list|clear>
cmux browser errors <list|clear>
与元素交互：
cmux browser click|dblclick|hover|focus|check|uncheck|scroll-into-view <selector> [--snapshot-after]
cmux browser type <selector> <text> [--snapshot-after]
cmux browser fill <selector> [text] [--snapshot-after]    # 空文本会清空输入框
cmux browser press|keydown|keyup <key> [--snapshot-after]
cmux browser select <selector> <value> [--snapshot-after]
cmux browser scroll [--selector <css>] [--dx <n>] [--dy <n>] [--snapshot-after]
查询元素：
cmux browser is <visible|enabled|checked> <selector>
cmux browser find <role|text|label|placeholder|alt|title|testid|first|last|nth> ...
cmux browser highlight <selector>
等待：
cmux browser wait [--selector <css>] [--text <text>] [--url-contains <text>] [--load-state <interactive|complete>] [--function <js>] [--timeout-ms <ms>]
JavaScript执行：
cmux browser eval <script>
页面操作：
cmux browser frame <selector|main>
cmux browser dialog <accept|dismiss> [text]
cmux browser viewport <width> <height>
cmux browser geolocation|geo <lat> <lon>
cmux browser offline <true|false>
cmux browser addscript <script>
cmux browser addstyle <css>
cmux browser addinitscript <script>
状态与网络：
cmux browser state <save|load> <path>
cmux browser cookies <get|set|clear> [...]
cmux browser storage <local|session> <get|set|clear> [...]
cmux browser download [wait] [--path <path>] [--timeout-ms <ms>]
cmux browser network <route|unroute|requests> [...]
cmux browser trace <start|stop> [path]
cmux browser screencast <start|stop>
cmux browser input <mouse|keyboard|touch>
浏览器标签页：
cmux browser tab <new|list|switch|close|<index>> [...]
浏览器识别：
cmux browser identify [--surface <id|ref|index>]

Hooks & Signals

钩子与信号

CommandDescription
set-hook [--list] [--unset <event>] | <event> <command>
Set/list/unset hooks
wait-for [-S|--signal] <name> [--timeout <seconds>]
Wait for or send a signal
CommandDescription
set-hook [--list] [--unset <event>] | <event> <command>
设置/列出/取消钩子
wait-for [-S|--signal] <name> [--timeout <seconds>]
等待或发送信号

Other

其他

CommandDescription
set-app-focus <active|inactive|clear>
Set app focus state
simulate-app-active
Simulate app becoming active
claude-hook <session-start|stop|notification> [--workspace] [--surface]
Claude session hooks
display-message [-p|--print] <text>
Display a message
bind-key
/ 
unbind-key
/ 
copy-mode
Key binding controls
popup
Show popup
CommandDescription
set-app-focus <active|inactive|clear>
设置应用聚焦状态
simulate-app-active
模拟应用变为活跃状态
claude-hook <session-start|stop|notification> [--workspace] [--surface]
Claude会话钩子
display-message [-p|--print] <text>
显示消息
bind-key
/ 
unbind-key
/ 
copy-mode
按键绑定控制
popup
显示弹窗

Common Patterns

常用场景示例

Discover current layout

查看当前布局

bash
cmux identify                    # Who am I?
cmux list-workspaces --json      # All workspaces
cmux list-panes --json           # All panes in current workspace
bash
cmux identify                    # 查看当前上下文
cmux list-workspaces --json      # 查看所有工作区
cmux list-panes --json           # 查看当前工作区的所有窗格

Run a command in a new split

在新分屏中运行命令

bash
cmux new-split right             # Create split to the right
bash
cmux new-split right             # 在右侧创建分屏

Then send a command to it (need to target the new surface)

然后向新分屏发送命令（需要指定新的表层）

cmux send --surface <new-surface-ref> "npm run dev" cmux send-key --surface <new-surface-ref> Enter
undefined
cmux send --surface <new-surface-ref> "npm run dev" cmux send-key --surface <new-surface-ref> Enter
undefined

Read what's on another terminal

读取其他终端的内容

bash
cmux read-screen --surface <ref>           # Current visible content
cmux read-screen --surface <ref> --scrollback --lines 200  # With scrollback
bash
cmux read-screen --surface <ref>           # 当前可见内容
cmux read-screen --surface <ref> --scrollback --lines 200  # 包含回滚历史

Open a browser alongside terminal

在终端旁打开浏览器

bash
cmux browser open http://localhost:3000
bash
cmux browser open http://localhost:3000

or as a directional split:

或者作为定向分屏打开：

cmux new-pane --type browser --direction right --url http://localhost:3000
undefined
cmux new-pane --type browser --direction right --url http://localhost:3000
undefined

Show progress in sidebar

在侧边栏显示进度

bash
cmux set-progress 0.5 --label "Building..."
cmux log --level info --source claude -- "Step 3/5 complete"
cmux set-status task "Running tests" --icon checkmark --color "#00ff00"
bash
cmux set-progress 0.5 --label "构建中..."
cmux log --level info --source claude -- "步骤3/5完成"
cmux set-status task "运行测试" --icon checkmark --color "#00ff00"

Tips

提示

  • Always use 
    --json
    when you need to parse output programmatically.
  • When creating splits/panes, capture the output to get the new surface/pane ID for subsequent commands.
  • read-screen
    is invaluable for checking what's happening in other terminals.
  • send
    sends raw text; remember to follow with 
    send-key Enter
    to execute a command.
  • Browser 
    snapshot
    gives you a DOM snapshot — use 
    --compact
    for a smaller representation.
  • Use 
    --snapshot-after
    on browser interaction commands to get the page state after the action.
  • 当你需要通过程序解析输出时始终使用
    --json
    参数。
  • 创建分屏/窗格时，捕获输出以获取新的表层/窗格ID，供后续命令使用。
  • read-screen
    对于检查其他终端的运行状态非常有用。
  • send
    发送原始文本；记得后续调用
    send-key Enter
    来执行命令。
  • 浏览器
    snapshot
    命令会返回DOM快照——使用
    --compact
    参数可以获得更小的返回内容。
  • 在浏览器交互命令上使用
    --snapshot-after
    参数可以获取操作后的页面状态。