v42 CLI
终端与 Agent
使用 v42 term、attach、ws enter 和 agents 创建、列出、查看、附着、发送按键或文本、读取屏幕、等待状态、监听变化、重命名、移动和关闭终端。
term、attach、ws enter 和 agents 命令让脚本和 coding agent 能够在当前团队的任意在线电脑上创建和控制终端。每个终端都是该电脑上真实持久化运行的窗口,与 Vibe42 App 实时共享。
目标标识语法(Target)
操作现有终端的命令接收 <computer>(ID 或名称)和 <target>:
@N:窗口 ID(例如@12)。针对单个 pane 的命令(term send、term read、term wait)在收到@N时作用于该窗口当前的活跃 pane。%N:pane ID(例如%5)。<session>:@N:v42 term new在.data.target中返回的完整窗口标识。<session>:tmux 会话名称(v42 term attach和v42 attach支持直接附着到整个会话)。
列出与查看终端
v42 term list [<computer>] [--workspace <workspace>] [--idle] [--busy]
v42 term status <computer> <target>term list:列出整个团队所有电脑(或指定<computer>)上的终端。不指定电脑时,离线或连不上的电脑在computers下报告其状态;指定了电脑(或 Workspace)时,这台电脑离线或连不上会直接报错(如computer_offline),而不是返回空列表。--workspace <workspace>:只列出属于该 Workspace(ID 或名称)的终端。--idle:只列出空闲(idle)终端。--busy:只列出非空闲终端(包括状态为unknown的终端)。
term status <computer> <target>:查看单个终端窗口、Agent 状态和空闲状态;窗口有多个 pane 时,另在panes中逐个列出。
空闲判定规则(Idle rule)
每个 pane 的 foreground 状态为以下三者之一:idle(shell 停在提示符处,前台没有程序运行)、busy(前台有程序运行)或 unknown(电脑是 Windows 或 Vibe42 版本较旧,或终端是在更新前创建的,无法上报前台状态)。
一个终端只有在同时满足以下两个条件时才判定为 idle(空闲):
- 每个 pane 的
foreground都是idle;且 - 它的 Agent 状态(如果有)为
idle或done(没有处于working、blocked或error的 Agent)。
当电脑无法判断状态(unknown)时,该终端一律按 busy(忙碌) 处理。除非显式传入 --force,否则 term close、block close 和 tab close 绝不会关闭忙碌或 unknown 的终端。
创建终端
v42 term new <computer> [options]在 <computer> 上创建终端,可选在其中启动 Agent 或命令,并把它放进所属 Workspace(--workspace)或该电脑的布局中。
| 选项 | 说明 |
|---|---|
--workspace <workspace> |
终端归属的 Workspace(ID 或名称);工作目录取该 Workspace 目录(开启终端隔离时为新建的隔离副本)。不能与 --cwd 同时使用。 |
--cwd <cwd> |
电脑上的起始工作目录(未传 --workspace 时使用)。 |
--name <name> |
终端窗口标题。 |
--launcher <launcher> |
启动 v42 agents list 中的指定 Agent 启动器 ID;未传 --name 时用启动器的显示名称命名终端。传 terminal 则打开普通终端。 |
--agent <agent> |
内置 Agent 目录 ID(claude-code、codex、omp、pi、opencode、grok-build、devin、antigravity、cursor 等);未传 --command 时运行该 Agent 的默认命令。 |
--command <command> |
在新终端中启动的单行命令(在交互式登录 shell 中运行)。 |
--tab <tab> |
在指定标签页(ID、从 1 开始的位置或标题)中打开终端;未传 --beside 或 --float 时排在该标签页最后一个块之后。 |
--beside <beside> |
在指定块旁边打开终端(块 ID、终端 %N / @N 或 --tab 内从 1 开始的位置)。 |
--side <side> |
在 --beside 块的哪一侧打开:left、right、up、down 或 auto(auto 默认为 right)。 |
--float |
在 --tab(或第一个标签页)中作为浮动块打开终端。 |
--no-layout |
不把终端放进任何布局(之后打开该布局的 App 会自动为它单独生成一个标签页)。 |
--no-balance |
放置终端后不自动重新均分所在分屏的比例。 |
--attach |
创建终端后立即附着上去。 |
--stdio |
配合 --attach 使用,为程序转发原始字节流而不接管本地终端界面。 |
term new、term close 与 term move 对布局的影响
term new:不传放置选项时,新终端会在所属 Workspace(或电脑)布局的顶部新建一个标签页打开;如果更新布局失败,终端本身仍会保留,.data.layout会报告placed: false及错误原因。传入--tab、--beside或--float时,会先校验目标位置,目标无效时不会创建终端。如果某个打开的 App 已经为新终端创建了块,则会把那个块移到指定位置,而不会重复打开两次。term close:等待电脑确认终端已关闭后,将该终端在所属 Workspace 或电脑布局中的所有块一并移除。term move:把窗口移到同一台电脑的另一个 Workspace(或用--none移出所有 Workspace),从原布局中移除它的块,并在目标布局顶部新建标签页打开它(除非目标布局中已经显示了该终端)。
附着到终端
v42 term attach <computer> <target> [--stdio]
v42 attach <computer> <target> [--stdio]
v42 ws enter <workspace> [--stdio]term attach(及其顶层简写attach)将当前终端连接到<computer>上的<target>。ws enter <workspace>在<workspace>所在的电脑和目录中新建一个终端并立即附着过去。
在 Windows 电脑上,term attach 只能连接整个会话,不能连接单个窗口或 pane。
这三条都是流式命令:stdout 仅包含远端 PTY 原始字节,退出码来自附着客户端。主动断开连接后,远端窗口继续保持运行。
由其他程序或终端复用器驱动 stdin/stdout 时,请加上 --stdio:
- stdin 不是 TTY 时,不改动本地终端设置,也不发送窗口尺寸。输入结束时(例如管道输入读完),会向远端终端发送
Ctrl+D,远端正在运行的 shell 会因此退出;只是发送一次性输入时请改用v42 term send。 - stdin 是 TTY 时,启用 raw 模式(
Ctrl+C作为按键发给远端),但只有在本进程向远端转发第一次输入之后才推送当前窗口尺寸(并在后续尺寸变化时继续同步)。 - 在 macOS 或 Linux 的 Herdr pane 内运行(
HERDR_ENV=1且设置了HERDR_PANE_ID)时,attach会给该 Herdr pane 打上v42_computer和v42_pane标记,并在附着期间把该 pane 的 Agent 状态实时上报给 Herdr(目标为窗口或 pane 时如此;目标为整个 session 时只写v42_computer,不上报状态)。
发送输入与读取屏幕
v42 term send <computer> <target> [<text>] [--stdin] [--enter] [--key <key>]... [--paste] [--raw]
v42 term read <computer> <target> [--history <lines> | --all] [--raw]term send
向 <target> 输入文本或按键,且不干扰正在查看该终端的其他连接。同时指定多项时,先输入 <text>(或 --stdin),再按顺序发送每个 --key,最后按 --enter。
--stdin:从标准输入读取要发送的文本(最多 8 MiB)。--enter:在文本和按键之后按下回车(Enter)。--key <key>:可重复指定。支持的按键名:enter、tab、backtab、escape、backspace、insert、delete、home、end、pageup、pagedown、up、down、left、right、space、f1–f35或单个字符。修饰键前缀:ctrl+、alt+、shift+、super+(如ctrl+c、alt+x、shift+tab)或 tmux 风格C-、M-、S-(如C-c、M-x、S-Tab)。--paste:用括号粘贴标记(ESC[200~…ESC[201~)包裹文本,让开启了 bracketed paste 的 shell 或 Agent 把多行文本当作一次粘贴处理。--raw:原样发送字节(允许非 UTF-8 输入;此时--enter追加回车符\r,且不能与--key同用)。
term read
在 .data.lines 中输出 <target> 当前可见屏幕的纯文本行(自动去掉末尾空行)。
--history <lines>:在可见屏幕之前一并输出最多<lines>行历史回滚内容(scrollback)。--all:在可见屏幕之前输出全部历史回滚内容。--raw:保留 ANSI 转义序列(历史行保留颜色,可见屏幕按换行符切分原始 VT 流)。
等待状态与监听事件
v42 term wait --until <state> [--match <pattern>] [--timeout <seconds>] <computer> <target>
v42 term watch [<computer>] [--workspace <workspace>] [--timeout <seconds>] [--count <count>]term wait
阻塞等待,直到 <target> 达到 --until <state> 指定的状态,并返回终端状态 JSON。如果 --timeout <seconds>(默认 600 秒;传 0 则无限等待)先到期,命令以错误码 wait_timeout 和退出码 8 结束。
--until 取值 |
返回时机 |
|---|---|
idle |
shell 回到提示符处且没有处于 working、blocked 或 error 的 Agent:在经历一段忙碌期后返回,或屏幕连续 1.5 秒保持未变后返回。需要电脑上运行较新的 Vibe42;Windows 电脑暂不支持(idle_windows_unsupported)。 |
done |
Agent 完成当前轮次:在等待期间观察到状态变为 done 时立即返回,或已持续处于 done 满 1.5 秒后返回。 |
blocked |
Agent 正在等待用户操作(权限确认、提问或登录)。若已处于该状态则立即返回。 |
error |
Agent 报告了错误。若已处于该状态则立即返回。 |
working |
Agent 正在工作。若已处于该状态则立即返回。 |
gone |
终端已关闭(传入窗口时为窗口关闭,传入 pane 时为该 pane 关闭);若开始等待时目标已不存在,则立即返回并标记 already_gone。 |
output |
可见屏幕发生变化;配合 --match <pattern> 时,等待出现一行开始等待时不存在且匹配正则表达式 <pattern> 的新屏幕行。 |
term watch
在 stdout 上以 JSON Lines(NDJSON,每行一个 JSON 对象)流式输出终端变化:
- 每台被监听的电脑先输出一行
ready(无法监听的电脑输出unavailable) - 随后实时输出变化事件:
terminal_added、terminal_removed、renamed、workspace_changed、agent_status和foreground - 达到
--count <count>条变化事件(ready和unavailable不计入)或到达--timeout <seconds>秒后,输出最后一行stopped并退出
省略 <computer> 时监听当前团队的所有在线电脑;传入 --workspace <workspace> 时只输出该 Workspace 下的终端事件。
重命名、移动与关闭终端
v42 term rename <computer> <target> [<name> | --reset]
v42 term move <computer> <window> <--workspace <workspace> | --none>
v42 term close <computer> [<targets>...] [--force] [--idle [--workspace <workspace>] [--dry-run]] [--no-balance]term rename:为窗口@N或 pane%N设置自定义名称(去除首尾空白后最多 64 个字符),或传--reset恢复自动名称。term move:把窗口@N移到同一台电脑的--workspace <workspace>,或传--none将其移出所有 Workspace,并同步更新两侧布局。term close:关闭一个或多个指定的窗口或 pane(<targets>...),或用--idle关闭<computer>上的所有空闲终端。- 指定
<targets>...时,只要其中有任何终端不是空闲状态(或状态为unknown),所有终端都不会被关闭,命令返回terminal_busy(退出码2),除非传入--force。 - 使用
--idle时,只关闭<computer>本机属于 Vibe42 的空闲终端(可加--workspace限定范围);忙碌终端以及从 Herdr 或外部 tmux 会话镜像过来的窗口(原因external_source)绝不会被关闭,并会列在.data.skipped中。搭配--dry-run可只列出将被关闭的终端而不实际关闭。 - 传入
--no-balance可在移除块后保持剩余分屏比例不变。
- 指定
管理 Agent 启动器(v42 agents)
App 新建终端流程展示的以及 v42 term new --launcher <id> 使用的 Agent 启动器列表在账号下跨设备同步,可通过 CLI 直接管理:
v42 agents list
v42 agents add --command <command> [--name <name>] [--agent <agent>]
v42 agents edit <id> [--name <name>] [--command <command>]
v42 agents rm <id>
v42 agents move --index <index> <id>
v42 agents resetagents list:列出当前生效的启动器列表(未自定义时为默认列表)以及内置 Agent 目录。agents add --command <command>:在列表末尾添加自定义启动器(分配 IDcustom-<n>)。<command>为不超过 1024 字节的单行命令,且不能以-开头。--name <name>设置显示名称(最多 64 个字符);--agent <agent>关联内置目录 ID 以便识别状态。agents edit <id>:修改启动器的--name(传--name ""恢复默认名称)或--command。agents rm <id>:移除指定启动器。agents move --index <index> <id>:将启动器移动到从 1 开始的指定位置。agents reset:清空所有自定义项,恢复默认 Agent 启动器列表。