CLI 参考

purplemux 提供两种使用方式:作为服务启动器(purplemux / purplemux start)和作为与运行中服务对话的 HTTP API 包装器(purplemux <subcommand>)。短别名 pmux 与之等价。

一个二进制,两种角色

bin/purplemux.js 中的分发器会剥离第一个参数:已知子命令路由到 bin/cli.js,其他(或没有参数)则启动服务。

启动服务

purplemux              # 默认
purplemux start        # 同上,显式
PORT=9000 purplemux    # 自定义端口
HOST=all purplemux     # 全部绑定

完整环境变量见 端口与环境变量。

服务会打印绑定的 URL、模式和认证状态:

  ⚡ purplemux  v0.x.x
  ➜  Available on:
       http://127.0.0.1:8022
       http://192.168.1.42:8022
  ➜  Mode:   production
  ➜  Auth:   configured

如果 8022 已被占用,服务会发出警告并改绑随机空闲端口。

子命令

所有子命令都需要一个运行中的服务。它们从 ~/.purplemux/port 读端口、从 ~/.purplemux/cli-token 读认证 token,这两个文件都会在服务启动时自动写好。

输出默认为 JSON。--workspace 和 -w 可互换。

tab create 面板类型

-t / --type 选择面板类型。有效值:

不带 -t 时,得到一个普通终端。

tab browser 子命令

只有当标签的面板类型是 web-browser,且仅在 macOS Electron 应用中工作时可用 — 否则桥接返回 503。

示例

# 找到工作区
purplemux workspaces

# 在 ws-MMKl07 工作区里创建一个 Claude 标签
purplemux tab create -w ws-MMKl07 -t claude-code -n "refactor auth"

# 给它发提示(TAB_ID 来自 `tab list`)
purplemux tab send -w ws-MMKl07 tb-abc "Refactor src/lib/auth.ts to remove the cookie path"

# 查看状态
purplemux tab status -w ws-MMKl07 tb-abc

# 抓取窗格内容
purplemux tab result -w ws-MMKl07 tb-abc

# 给一个 Web 浏览器标签整页截图
purplemux tab browser screenshot -w ws-MMKl07 tb-xyz -o page.png --full

认证

每个子命令都发送 x-pmux-token: $(cat ~/.purplemux/cli-token),服务端用 timingSafeEqual 校验。~/.purplemux/cli-token 文件在首次服务启动时通过 randomBytes(32) 生成,以 0600 模式存放。

如果你需要从看不到 ~/.purplemux/ 的另一个 shell 或脚本驱动 CLI,改用环境变量:

PMUX_PORT=8022 PMUX_TOKEN=$(cat ~/.purplemux/cli-token) purplemux workspaces

update-notifier

purplemux 在每次启动时检查 npm 上是否有更新版本(通过 update-notifier),并在有新版本时打印横幅。用 NO_UPDATE_NOTIFIER=1 或任意 update-notifier 标准退出方式 关闭。

完整 HTTP API

purplemux api-guide 打印每个 /api/cli/* endpoint 的完整 HTTP API 参考,包括请求体和响应结构 — 当你想直接用 curl 或其他运行时驱动 purplemux 时很有用。

下一步

• 端口与环境变量 — PMUX_PORT / PMUX_TOKEN 在更广环境变量中的位置。
• 架构 — CLI 实际在跟谁通信。
• 故障排查 — 当 CLI 说 "服务在运行吗?" 的时候。