v42 CLI

终端与 Agent

使用 v42 term、attach、ws enter 和 agents 创建、列出、查看、附着、发送按键或文本、读取屏幕、等待状态、监听变化、重命名、移动和关闭终端。

查看 Markdown 原文

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 支持直接附着到整个会话)。

列出与查看终端

sh
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(空闲):

  1. 每个 pane 的 foreground 都是 idle;且
  2. 它的 Agent 状态(如果有)为 idle 或 done(没有处于 working、blocked 或 error 的 Agent)。

当电脑无法判断状态(unknown)时,该终端一律按 busy(忙碌) 处理。除非显式传入 --force,否则 term close、block close 和 tab close 绝不会关闭忙碌或 unknown 的终端。

创建终端

sh
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),从原布局中移除它的块,并在目标布局顶部新建标签页打开它(除非目标布局中已经显示了该终端)。

附着到终端

sh
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,不上报状态)。

发送输入与读取屏幕

sh
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 流)。

等待状态与监听事件

sh
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 对象)流式输出终端变化:

  1. 每台被监听的电脑先输出一行 ready(无法监听的电脑输出 unavailable)
  2. 随后实时输出变化事件:terminal_added、terminal_removed、renamed、workspace_changed、agent_status 和 foreground
  3. 达到 --count <count> 条变化事件(ready 和 unavailable 不计入)或到达 --timeout <seconds> 秒后,输出最后一行 stopped 并退出

省略 <computer> 时监听当前团队的所有在线电脑;传入 --workspace <workspace> 时只输出该 Workspace 下的终端事件。

重命名、移动与关闭终端

sh
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 直接管理:

sh
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 reset
  • agents list:列出当前生效的启动器列表(未自定义时为默认列表)以及内置 Agent 目录。
  • agents add --command <command>:在列表末尾添加自定义启动器(分配 ID custom-<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 启动器列表。