v42 CLI
电脑、设备、桌面与网络
使用 v42 computer、device、desktop 和 network 管理团队电脑与已配对设备、截取并控制远程桌面及其窗口与菜单,以及诊断 AP 和 P2P 网络路径。
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;按键是物理键,可写 DOMKeyboardEvent.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 probenetwork [<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:重新测量所有接入点的延迟并输出最新结果。