v42 CLI

Files and port forwarding

Browse, inspect, search, create, delete, copy, and sync files on any Computer, or forward TCP ports with v42 ls, stat, find, mkdir, rm, cp, sync, and forward.

View as Markdown

Every file command in v42 accepts either a local path or a remote path in <computer>:/absolute/path form (<computer> is a Computer ID or name). File operations run over the dedicated file channel so they never slow down active terminals.

Listing, inspecting, and searching files

sh
v42 ls [-a] [-l] <location>
v42 stat [--no-follow] <location>
v42 find <location> <query> [--limit <limit>]
  • ls <location>: List a directory. Folders come first, then files, in natural name order. Up to 10,000 entries are returned (when more exist, .data.truncated is true).
    • -a, --all: Include entries whose names start with ..
    • -l, --long: Return each entry as an object with name, kind (file, dir, symlink, other), size, and mtime_ms. (Use v42 stat --no-follow when you need mode permissions.)
  • stat <location>: Show metadata for a single file or directory.
    • --no-follow: Describe a symbolic link itself instead of its target, and include file permissions (mode).
  • find <location> <query>: Case-insensitive substring search on file names below <location>. Entries starting with . and node_modules directories are skipped. The search stops after --limit <limit> matches (1 to 200, default 200), 20,000 visited entries, or 2 seconds, setting truncated: true when stopped early.

Creating and deleting directories and files

sh
v42 mkdir [-p] <location>
v42 rm [-r] [--yes] <location>
  • mkdir <location>: Create a directory locally or on <computer>.
    • -p, --parents: Create missing parent directories too, and succeed when the directory already exists.
  • rm <location>: Delete a file, symbolic link, or directory. Symbolic links are removed themselves, never their target.
    • -r, --recursive: Delete a directory together with everything inside it (requires --yes). Without --yes, nothing is deleted and the command fails with confirmation_required (exit 2), reporting in error.details how many entries would be deleted.
    • The filesystem root (/), the user's home directory, and parent directories above home are always refused.

Copying and synchronizing files

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

<source> and <destination> can be local paths or <computer>:/absolute/path coordinates in any combination (local to remote, remote to local, or Computer A to Computer B).

  • cp: Copy a file or directory.
    • -r, --recursive: Copy a directory and its contents recursively. If <destination> is an existing directory, the source's base name is created inside it.
    • --restart: Discard interrupted partial transfers for this operation and start over from the beginning.
  • sync: Synchronize the contents of <source> directory into <destination> directory in one direction.
    • By default, extra entries in <destination> are kept.
    • --delete: Delete destination entries that are not in <source>. Deletion runs only after all copies succeed and the source manifest is verified unchanged.
    • --restart: Discard interrupted partial transfers and start over.
    • cp and sync refuse a destination that is, contains, or is inside the source on the same machine (invalid_argument). Paths are compared ignoring letter case, and a local path counts as the same machine as <this computer>:/path when v42 signs in through that Computer's Vibe42.

Transfer integrity and resume

Files are verified with both per-chunk and whole-file SHA-256 checksums, written to a .part file first, and committed atomically only after verification passes. If a transfer is interrupted, running the same cp or sync command again resumes from the saved offset. If the source file changed in the meantime, the command fails with resume_source_changed; pass --restart to copy from the start.

Port forwarding (v42 forward)

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

Listens on a local TCP port and forwards incoming connections over an end-to-end encrypted tunnel to 127.0.0.1:<remote-port> on <computer>:

sh
v42 forward my-mac:3000 3000
v42 forward my-mac:5432 127.0.0.1:15432
v42 forward my-mac:3000 0
  • When <local-addr> is omitted, the listener binds to 127.0.0.1 only. Binding to a non-loopback address prints a warning on stderr.
  • Setting <local-port> to 0 lets the OS pick a free port; once ready, the listener writes a forward_listening JSON notice to stderr with the bound address and port.
  • Up to 64 simultaneous TCP connections are supported, preserving TCP half-close semantics.
  • Stop forwarding with Ctrl+C (SIGINT) or SIGTERM. Relayed traffic counts toward Credits and usage when the connection runs through an AP.