v42 CLI

Computers, devices, desktop, and network

Manage Computers and devices, take screenshots of and control remote desktops, their windows, apps, and menus, and diagnose AP and P2P network paths with v42 computer, device, desktop, and network.

View as Markdown

The computer, device, desktop, and network command groups inspect and manage your Team's machines, your signed-in apps and CLIs, remote desktops (screenshots, video, mouse, keyboard, and clipboard) with their windows and menus, and network connectivity.

Managing Computers (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: List every Computer in the current Team with its online, paused, and relay state, sharing mode, Vibe42 version, platform, featureset, and active terminal count.
  • computer show <computer>: Show one Computer (by ID or name), including its Realm, host install, and access restrictions.
  • computer rename <computer> <name>: Rename a Computer (1 to 64 characters, trimmed; Team owners, admins, or the Computer's owner).
  • computer pause <computer> / computer resume <computer>: Pause a Computer so nobody can connect until it is resumed, or resume a paused Computer (Team owners and admins only; resume fails with resource_limit_exceeded if the Team has no free Computer slot).
  • computer relay <computer> <on|off>: Turn relay-only routing (on) or automatic direct P2P (off) on a Computer (Team owners, admins, or the Computer's owner).
  • computer share <computer> <private|team>: Share a Computer with the whole Team (team) or restrict it to its owner plus Team owners and admins (private). Only the Computer's owner can change this.
  • computer remove <computer> --yes: Remove a Computer from the Team, revoking its credentials and deleting its cloud Workspace records (Team owners and admins only; requires --yes, otherwise fails with confirmation_required). Local files on the machine are never touched.
  • computer cleanup [--dry-run] [--yes]: Remove Computers that have been offline for more than 3 days (Team owners and admins). Without --dry-run or --yes, fails with confirmation_required and lists the candidate Computers in error.details.
  • computer herdr <computer>: Show a Computer's Herdr bridge status, or update its settings with --enable, --disable, or --sessions <sessions> (comma-separated additional Herdr instance names; pass "" to clear). Restricted to the Computer's owner on macOS or Linux.

Managing devices and pairings (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: List your own devices (installs) and the devices with access to the current Team (team_installs; Team owners and admins see every member's devices). current: true marks the Install this CLI profile uses. Pass --all to include signed-out and revoked devices.
  • device approve <code>: Approve an 8-character pairing code shown on a new Computer, adding it to the current Team (requires permission to register Computers).
  • device unpair <install_id>: Sign out one of your own Apps or browsers (install_id from installs in v42 device list). Cannot be used on the device currently running the command (use v42 logout instead).
  • device cleanup [--dry-run] [--yes]: Sign out your own devices that have been offline for more than 3 days, except those currently in use. Without --dry-run or --yes, fails with confirmation_required and lists the candidates.
  • device revoke <install_id>: Revoke a device's access to the current Team and free its device slot. Note that removing a Computer (v42 computer remove) does not free its host device slot—revoke the corresponding install_id from v42 resources or v42 device list when replacing a dynamic machine.

Controlling desktop windows, apps, and menus (v42 desktop)

Requires remote desktop with remote control enabled on the target Computer (see Remote Desktop). The window, app, and menu commands below need desktop.windows.v1 in the Computer's featureset.

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>: List the displays and open desktop windows of <computer>.
  • desktop apps <computer>: List applications that can be launched on <computer>, with names localized to the CLI locale.
  • desktop launch <computer> <app>: Launch an app on <computer> (or activate it if already running) and return its front window. <app> can be an app path, bundle ID, name, or localized name from v42 desktop apps (case-insensitive).
  • desktop window <computer> <id> <action>: Perform close, minimize, or full-screen on window <id> (from v42 desktop windows).
  • desktop menu <computer> <window>: Show the menu bar tree of <window>'s application. Each menu item includes a path array of comma-separated indexes.
  • desktop menu-press --title <title> <computer> <window> <path>...: Press a menu item in <window> using its path from v42 desktop menu (top level first, counting separators, such as 2,5). --title <title> is required as a safety check: the press is refused if the menu item's title no longer matches <title>.

Screenshots, video, and input

These commands open a remote desktop session and need desktop.v1 in the Computer's featureset (desktop_unsupported otherwise). The clipboard commands also need desktop.clipboard.v1, --window needs desktop.windows.v1, and unlock needs desktop.unlock.v1; a missing one fails with 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: Save what a display (or, with --window, one window, which is brought to the front) shows as a PNG. The CLI waits until the picture has been still for 0.7 seconds (at most 3 seconds) and decodes the video itself: with VideoToolbox on macOS, and with the system ffmpeg on Linux and Windows (desktop_decoder_unavailable when it is missing). The result reports the image width and height, the codec, the display (with its native width and height), the window, and whether the Computer can be controlled. -o - writes only the PNG to stdout. --quality is low, balanced, high (default), ultra, or auto; Computers that do not offer ultra or auto get high or balanced.
  • desktop stream: Write the raw Annex B H.264 (or, with --codec hevc, HEVC) video to stdout or a file. Picture changes are reported as JSON on stderr; writing to a file prints a summary at the end. It stops with exit code 0 at --duration or --frames, 130 on SIGINT, and 143 on SIGTERM. With --window, it also stops with exit code 0 (reason window_closed) when the window closes, its app quits, or it stays off screen, instead of recording the whole display; desktop screenshot --window fails with window_not_found in that case. --duration and --timeout are at most 30 days.
  • Coordinates are native pixels of the display (0 to display.width − 1 and 0 to display.height − 1), not pixels of the screenshot, which is often scaled down: multiply image positions by display.width / width. With --window <id> (from v42 desktop windows or v42 desktop launch; it needs desktop.windows.v1 and cannot be combined with --display), the command first selects that window, which the Computer restores, brings to the front, and keeps in front while it injects the input; coordinates are then native pixels of the window's capture area (window.width, window.height). key, type, and clipboard copy take --window too, so keys and text reach that window rather than whatever has focus. An unknown window fails with window_not_found.
  • desktop move, click, drag, scroll: Pointer input. --count 2 is a double click. Positive --dy scrolls the content down, like a web page's wheel event.
  • desktop key: Press keys or combinations in order, for example cmd+shift+4, ctrl+c, alt+tab, enter. Modifiers are cmd (also command, meta, super, win), ctrl, alt (also option), and shift; keys are physical keys, written as a DOM KeyboardEvent.code (KeyA, Digit1, ArrowUp, F5) or a name such as a, 1, esc, tab, up, pagedown, or a punctuation character. cmd is the Command key on a Mac and the Windows key elsewhere.
  • desktop type: Type text into the focused app (at most 64 KiB). As in the apps, a line break inside the text is sent as Shift+Enter; to press Enter, use desktop key <computer> enter.
  • Input commands (move, click, drag, scroll, key, type) wait an estimated time for the Computer to apply the input, then disconnect, and the Computer drops input it has not applied yet. On a slow Computer, such as a virtual machine or a busy host, a command can report success while part of its text or keys never arrived: check the result with desktop screenshot or desktop clipboard copy, and use desktop control for long text or many steps, since it keeps the session open.
  • desktop clipboard set writes plain text (at most 60 KiB) to the Computer's clipboard. clipboard watch prints one JSON line per change made after it started (ready, clipboard, then stopped). clipboard copy presses the copy shortcut (cmd+c on a Mac, ctrl+c elsewhere) and returns the copied text, or fails with clipboard_unchanged.
  • desktop unlock: Type the password of the user signed in on the Computer into its lock screen. The password is read from standard input only, without echo on a terminal. result is unlocked or not_locked; a wrong password fails with unlock_wrong_password.
  • desktop control: Keep one session open for many steps. Each line on stdin is a JSON request such as {"id":1,"op":"click","x":1520,"y":830}, and each answer is one line {"id":1,"ok":true,"data":…}. Ops are screenshot (with path, or the PNG as png_base64), move, click, drag, scroll, key, type, clipboard_set, clipboard_watch, select_display, select_window, unlock, status, and close; status, clipboard, and bye events come as {"event":…} lines. It ends when stdin ends.

Input needs remote control to be allowed on the Computer (desktop_view_only, exit code 4, when it can only be viewed). The Computer does not confirm input, so each input command waits until the Computer has had time to apply it (200 ms for keys and the pointer, longer for text) before it returns. Opening a session wakes the Computer's display; when the Computer can be controlled and the pointer is on another display, the pointer moves to the center of the captured display. Video relayed through an access point counts as traffic.

Network diagnostics and AP selection (v42 network)

sh
v42 network [<computer>]
v42 network aps
v42 network lock [<ap_id> | --clear]
v42 network probe
  • network [<computer>]: Diagnose the connection to the relay access point (AP)—reporting ap_path, ap_round_trip_ms, ap_lanes (control, terminal, file), and NAT observations—and, when <computer> is given, wait up to 8 seconds to measure the connection to that Computer (p2p_allowed, p2p_connected, and per-lane paths quic, tcp, or relay). Pass the global --force-relay flag to measure the relay path without waiting for direct P2P.
  • network aps: List all relay access points with their region, supported protocols, and measured round-trip time.
  • network lock [<ap_id> | --clear]: Prefer <ap_id> (from v42 network aps) for this CLI profile starting with the next command, or pass --clear to return to automatic selection. If a locked AP becomes unhealthy or unreachable, the CLI falls back automatically.
  • network probe: Re-measure every access point and print the updated results.