v42 CLI

文件与端口转发

使用 v42 ls、stat、find、mkdir、rm、cp、sync 和 forward 在任意电脑上浏览、查看、搜索、创建、删除、复制和同步文件,或转发本地 TCP 端口。

查看 Markdown 原文

v42 的所有文件命令均同时接受本机路径与 <computer>:/绝对路径 形式的远端路径(<computer> 为电脑 ID 或名称)。文件操作通过独立的 file 通道传输,不会拖慢正在使用的终端。

列出、查看与搜索文件

sh
v42 ls [-a] [-l] <location>
v42 stat [--no-follow] <location>
v42 find <location> <query> [--limit <limit>]
  • ls <location>:列出目录内容。文件夹排在前面,文件排在后面,按自然名称顺序排列;最多返回 10,000 个条目(超出时 .data.truncated 为 true)。
    • -a, --all:包含名称以 . 开头的隐藏条目。
    • -l, --long:将每个条目作为对象返回,包含 name、kind(file、dir、symlink、other)、size 和 mtime_ms。(如需查看权限 mode,请使用 v42 stat --no-follow。)
  • stat <location>:查看单个文件或目录的元数据。
    • --no-follow:查看符号链接(symlink)本身而非其指向的目标,同时返回权限信息(mode)。
  • find <location> <query>:在 <location> 下按文件名进行不区分大小写的子串搜索。自动跳过以 . 开头的条目和 node_modules 目录;匹配满 --limit <limit> 条(1 到 200,默认 200)、访问满 20,000 个条目或耗时满 2 秒时停止搜索,并在提前停止时标记 truncated: true。

创建与删除目录和文件

sh
v42 mkdir [-p] <location>
v42 rm [-r] [--yes] <location>
  • mkdir <location>:在本机或 <computer> 上创建目录。
    • -p, --parents:一并创建缺失的父目录,且在目录已存在时不报错。
  • rm <location>:删除文件、符号链接或目录。删除符号链接时只删除链接本身,绝不删除其指向的目标。
    • -r, --recursive:递归删除目录及其内部的所有内容(必须配合 --yes)。未传 --yes 时不会删除任何内容,命令以 confirmation_required(退出码 2)失败,并在 error.details 中报告将删除多少个条目。
    • 文件系统根目录(/)、用户主目录(Home)以及主目录的上级父目录始终被拒绝删除。

复制与同步文件

sh
v42 cp [-r] [--restart] <source> <destination>
v42 sync [--delete] [--restart] <source> <destination>

<source> 和 <destination> 可以任意组合本机路径与 <computer>:/绝对路径(本机到远端、远端到本机,或电脑 A 到电脑 B)。

  • cp:复制文件或目录。
    • -r, --recursive:递归复制目录及其内容。如果 <destination> 是已存在的目录,则会在其中创建以源目录名命名的子目录。
    • --restart:丢弃该操作之前未完成的断点续传状态,从头重新复制。
  • sync:将 <source> 目录的内容单向同步到 <destination> 目录。
    • 默认情况下,<destination> 中多出的条目会保留。
    • --delete:删除 <destination> 中不在 <source> 里的多余条目。只有在所有文件复制成功且复核源目录清单未发生变化后,才会逐项执行删除。
    • --restart:丢弃未完成的断点续传状态,从头重新同步。
    • 同一台机器上,目标与源相同、包含源或位于源之内时,cp 和 sync 会拒绝执行(invalid_argument)。路径比较不区分大小写;v42 通过某台电脑上的 Vibe42 登录时,本机路径与 <这台电脑>:/路径 视为同一台机器。

传输完整性与断点续传

文件传输采用分块与整文件双重 SHA-256 校验,先写入 .part 临时文件,校验通过后才原子提交为正式文件。如果传输中途中断,再次运行相同的 cp 或 sync 命令会自动从上次保存的偏移量继续传输。如果期间源文件发生了变化,命令会返回 resume_source_changed;此时可加上 --restart 从头复制。

端口转发(v42 forward)

sh
v42 forward <computer>:<remote-port> [<local-addr>:]<local-port>

在本机监听一个 TCP 端口,并通过端到端加密通道将传入连接转发到 <computer> 的回环地址 127.0.0.1:<remote-port>:

sh
v42 forward my-mac:3000 3000
v42 forward my-mac:5432 127.0.0.1:15432
v42 forward my-mac:3000 0
  • 省略 <local-addr> 时,默认只绑定本机 127.0.0.1。绑定到非回环地址时会在 stderr 打印安全警告。
  • 将 <local-port> 设为 0 时,由操作系统自动分配空闲端口,并在就绪后向 stderr 输出包含实际监听地址和端口的 forward_listening JSON。
  • 最多同时支持 64 条并发 TCP 连接,并保留 TCP 半关闭语义。
  • 按 Ctrl+C(SIGINT)或发送 SIGTERM 停止转发。连接经过 AP 中转时,转发流量计入 Credits 与用量。