v42 CLI

电脑、设备、桌面与网络

使用 v42 computer、device、desktop 和 network 管理团队电脑与已配对设备、截取并控制远程桌面及其窗口与菜单,以及诊断 AP 和 P2P 网络路径。

查看 Markdown 原文

computer、device、desktop 和 network 四个命令组用于查看和管理团队下的电脑、你已登录的 App 与 CLI 设备、远程桌面(截图、视频、鼠标、键盘与剪贴板)及其窗口与菜单,以及网络连接状态。

管理电脑(v42 computer)

sh
v42 computer list
v42 computer show <computer>
v42 computer rename <computer> <name>
v42 computer pause <computer>
v42 computer resume <computer>
v42 computer relay <computer> <on|off>
v42 computer share <computer> <private|team>
v42 computer remove <computer> --yes
v42 computer cleanup [--dry-run] [--yes]
v42 computer herdr <computer> [--enable | --disable] [--sessions <sessions>]
  • computer list:列出当前团队的所有电脑及其在线状态、暂停状态、中转模式、共享范围、Vibe42 版本、系统平台、featureset 以及活动终端数。
  • computer show <computer>:按 ID 或名称查看单台电脑详情,包括其 Realm、宿主安装及访问限制。
  • computer rename <computer> <name>:重命名电脑(去除首尾空白后 1 到 64 个字符;限团队 Owner、Admin 或该电脑的拥有者)。
  • computer pause <computer> / computer resume <computer>:暂停电脑(恢复前无人可连接)或恢复已暂停的电脑(仅限团队 Owner 和 Admin;如果团队没有空闲的电脑名额,resume 会以 resource_limit_exceeded 失败)。
  • computer relay <computer> <on|off>:开启(on)或关闭(off)该电脑的强制中转路由(限团队 Owner、Admin 或该电脑的拥有者)。
  • computer share <computer> <private|team>:将电脑共享给整个团队(team),或设为仅对电脑拥有者及团队 Owner/Admin 可用(private)。仅该电脑的拥有者可修改此项。
  • computer remove <computer> --yes:将电脑从团队中移除,撤销其凭据并删除云端保存的 Workspace 记录(仅限团队 Owner 和 Admin;必须传 --yes,否则返回 confirmation_required)。电脑磁盘上的本地文件不会受到任何影响。
  • computer cleanup [--dry-run] [--yes]:移除离线超过 3 天的电脑(仅限团队 Owner 和 Admin)。不传 --dry-run 或 --yes 时以 confirmation_required 失败,并在 error.details 中列出候选电脑。
  • computer herdr <computer>:查看电脑的 Herdr 桥接状态,或用 --enable、--disable、--sessions <sessions>(除默认实例外要连接的额外 Herdr 实例名,以逗号分隔;传空字符串 "" 清空列表)修改配置。仅限该电脑拥有者在 macOS 或 Linux 上使用。

管理设备与配对请求(v42 device)

sh
v42 device list [--all]
v42 device approve <code>
v42 device unpair <install_id>
v42 device cleanup [--dry-run] [--yes]
v42 device revoke <install_id>
  • device list:列出你自己的设备(installs)以及有权访问当前团队的设备(team_installs;团队 Owner 和 Admin 可看到所有成员的设备)。current: true 标记当前 CLI 配置档案正在使用的设备。加上 --all 可一并包含已退出和已撤销的设备。
  • device approve <code>:批准新电脑上显示的 8 位配对码,将其加入当前团队(需具备注册电脑的权限)。
  • device unpair <install_id>:将你自己的某个 App 或浏览器退出登录(<install_id> 取自 v42 device list 的 installs)。不能用于退出当前正在运行命令的设备本身(请改用 v42 logout)。
  • device cleanup [--dry-run] [--yes]:将你自己离线超过 3 天(且当前未在使用)的设备退出登录。不传 --dry-run 或 --yes 时以 confirmation_required 失败并列出候选设备。
  • device revoke <install_id>:撤销某台设备对当前团队的访问权限并释放其占用的设备名额。注意:移除电脑(v42 computer remove)不会自动释放其宿主设备的名额;动态替换电脑时,请从 v42 resources 或 v42 device list 中找到对应的 install_id 并执行 device revoke。

控制桌面窗口、应用与菜单(v42 desktop)

需要目标电脑已开启远程桌面与远程控制(见远程桌面:开始使用)。下面的窗口、应用与菜单命令要求电脑 featureset 包含 desktop.windows.v1。

sh
v42 desktop windows <computer>
v42 desktop apps <computer>
v42 desktop launch <computer> <app>
v42 desktop window <computer> <id> <close|minimize|full-screen>
v42 desktop menu <computer> <window>
v42 desktop menu-press --title <title> <computer> <window> <path>...
  • desktop windows <computer>:列出 <computer> 桌面的显示器和已打开窗口。
  • desktop apps <computer>:列出 <computer> 上可启动的应用程序(名称按 CLI 语言本地化)。
  • desktop launch <computer> <app>:在 <computer> 上启动应用(已运行时则激活它)并返回其最前端窗口。<app> 可传应用路径,或 v42 desktop apps 中的 bundle ID、名称或本地化名称(不区分大小写)。
  • desktop window <computer> <id> <action>:对窗口 <id>(来自 v42 desktop windows)执行 close(关闭)、minimize(最小化)或 full-screen(全屏)。
  • desktop menu <computer> <window>:查看桌面窗口 <window> 所属应用的菜单栏结构。每个菜单项都带有 path 路径索引。
  • desktop menu-press --title <title> <computer> <window> <path>...:点击 <window> 中的某个菜单项,<path>... 取自 v42 desktop menu(从顶层开始、包含分隔线的逗号分隔索引,如 2,5)。必须传入 --title <title> 作为安全校验:如果该菜单项当前的标题已不再匹配 <title>,点击会被拒绝。

截图、视频与输入

这些命令会打开一个远程桌面会话,要求电脑 featureset 包含 desktop.v1(否则返回 desktop_unsupported)。剪贴板命令还需要 desktop.clipboard.v1,--window 需要 desktop.windows.v1,unlock 需要 desktop.unlock.v1;缺少时返回 desktop_feature_unsupported。

sh
v42 desktop screenshot <computer> -o <file.png|-> [--display <id> | --window <id>] [--quality <q>] [--max-width <n>] [--max-height <n>]
v42 desktop stream <computer> [-o <file|->] [--codec h264|hevc] [--duration <s>] [--frames <n>] [--display <id> | --window <id>] [--quality <q>]
v42 desktop move <computer> <x> <y> [--display <id> | --window <id>]
v42 desktop click <computer> <x> <y> [--button left|right|middle] [--count 1-3] [--display <id> | --window <id>]
v42 desktop drag <computer> <x1> <y1> <x2> <y2> [--button <b>] [--steps <n>] [--display <id> | --window <id>]
v42 desktop scroll <computer> [--at <x> <y>] [--dx <n>] [--dy <n>] [--display <id> | --window <id>]
v42 desktop key <computer> <combo>... [--window <id>]
v42 desktop type <computer> [<text> | --stdin] [--window <id>]
v42 desktop clipboard set <computer> [<text> | --stdin]
v42 desktop clipboard watch <computer> [--timeout <s>] [--count <n>]
v42 desktop clipboard copy <computer> [--timeout <s>] [--window <id>]
v42 desktop unlock <computer>
v42 desktop control <computer> [--display <id>] [--quality <q>]
  • desktop screenshot:把显示器(或用 --window 指定的单个窗口,会被提到最前)的画面存成 PNG。CLI 等画面静止 0.7 秒(最多 3 秒)后自行解码视频:macOS 用 VideoToolbox,Linux 与 Windows 调用系统的 ffmpeg(找不到时返回 desktop_decoder_unavailable)。结果包含图像的 width、height、codec、display(含显示器原生 width、height)、window,以及电脑是否可控制(control)。-o - 时 stdout 只输出 PNG。--quality 可选 low、balanced、high(默认)、ultra、auto,不支持 ultra 或 auto 的电脑分别按 high、balanced 处理。
  • desktop stream:把原始 Annex B 格式的 H.264(--codec hevc 时为 HEVC)视频写到 stdout 或文件。画面变化以 JSON 写到 stderr;写文件时结束后输出摘要。到达 --duration 或 --frames 时以退出码 0 结束,SIGINT 为 130,SIGTERM 为 143。带 --window 时,如果窗口关闭、所属应用退出或长时间离屏,也会以退出码 0 结束(reason 为 window_closed),不会转而录下整个显示器;此时 desktop screenshot --window 返回 window_not_found。--duration 与 --timeout 最长 30 天。
  • 坐标是显示器的原生像素(0 到 display.width − 1、0 到 display.height − 1),不是截图的像素,截图常被缩小:图像上的位置要乘以 display.width / width。传 --window <id>(取自 v42 desktop windows 或 v42 desktop launch;需要 desktop.windows.v1,不能与 --display 同时使用)时,命令先选中该窗口:电脑会恢复它、把它提到最前,并在注入输入时保持它在最前;坐标改为该窗口采集区域的原生像素(window.width、window.height)。key、type 和 clipboard copy 也接受 --window,按键和文字会落在该窗口,而不是当前有焦点的应用。窗口不存在时返回 window_not_found。
  • desktop move、click、drag、scroll:指针输入。--count 2 为双击。--dy 为正时内容向下滚动,与网页滚轮事件一致。
  • desktop key:依次按下按键或组合键,例如 cmd+shift+4、ctrl+c、alt+tab、enter。修饰键为 cmd(也可写 command、meta、super、win)、ctrl、alt(也可写 option)和 shift;按键是物理键,可写 DOM KeyboardEvent.code(KeyA、Digit1、ArrowUp、F5),或 a、1、esc、tab、up、pagedown、标点字符等名称。cmd 在 Mac 上是 Command 键,在其他电脑上是 Windows 键。
  • desktop type:向当前聚焦的应用输入文字(最多 64 KiB)。与 App 一致,文字中的换行按 Shift+Enter 发送;要按回车请用 desktop key <computer> enter。
  • 输入类命令(move、click、drag、scroll、key、type)发完后按估算时间等待电脑注入,再断开连接,电脑会丢弃尚未注入的输入。电脑很慢时(例如虚拟机或负载很高的主机),命令可能报告成功,但部分文字或按键并没有到达:请用 desktop screenshot 或 desktop clipboard copy 核对结果;长文本或连续操作请用 desktop control,它在会话结束前一直保持连接。
  • desktop clipboard set 把纯文本(最多 60 KiB)写入电脑剪贴板。clipboard watch 对开始监听之后的每次变化输出一行 JSON(依次为 ready、clipboard、stopped)。clipboard copy 按下复制快捷键(Mac 为 cmd+c,其他电脑为 ctrl+c)并返回复制得到的 text,没有新内容时返回 clipboard_unchanged。
  • desktop unlock:在电脑的锁屏上代为输入当前登录用户的密码。密码只从标准输入读取,在终端上不回显。result 为 unlocked 或 not_locked;密码错误时返回 unlock_wrong_password。
  • desktop control:在一个会话里连续执行多步操作。stdin 每行是一个 JSON 请求,例如 {"id":1,"op":"click","x":1520,"y":830},每个结果占一行 {"id":1,"ok":true,"data":…}。支持的 op 有 screenshot(传 path 写文件,否则以 png_base64 返回 PNG)、move、click、drag、scroll、key、type、clipboard_set、clipboard_watch、select_display、select_window、unlock、status 和 close;status、clipboard、bye 事件以 {"event":…} 行输出。stdin 结束时退出。

输入需要电脑允许远程控制(只能观看时返回 desktop_view_only,退出码 4)。电脑不会回执输入,因此每条输入命令都会等电脑有足够时间执行后才返回(按键和指针 200 毫秒,文字更久)。打开会话会唤醒电脑的显示器;电脑可控制且指针在其他显示器上时,指针会被移到所采集显示器的中央。经接入点中转的视频计入流量。

网络诊断与接入点选择(v42 network)

sh
v42 network [<computer>]
v42 network aps
v42 network lock [<ap_id> | --clear]
v42 network probe
  • network [<computer>]:诊断到中转接入点(AP)的网络路径(返回 ap_path、ap_round_trip_ms、按 control/terminal/file 顺序排列的 ap_lanes 以及 NAT 观测结果);传入 <computer> 时还会最多等待 8 秒以测量到该电脑的连接状态(p2p_allowed、p2p_connected 以及各通道是 quic、tcp 还是 relay)。传入全局选项 --force-relay 可仅测量中转路径而不等待直连。
  • network aps:列出所有中转接入点(AP)及其区域、支持的协议和实测往返耗时。
  • network lock [<ap_id> | --clear]:从下一条命令起让当前配置档案优先使用指定的 <ap_id>(来自 v42 network aps),或传 --clear 恢复自动选择。如果锁定的 AP 不健康或不可达,CLI 会自动回退到可用节点。
  • network probe:重新测量所有接入点的延迟并输出最新结果。