v42 CLI

Workspaces, memos, and copies

Create and manage Workspaces, edit and send Workspace memos, and inspect or apply terminal-isolation copies locally or remotely with v42 ws, memo, and copy.

View as Markdown

The ws, memo, and copy command groups manage Workspaces, Workspace memos, and terminal-isolation copies. All three work over the network from any signed-in machine, and v42 copy also works locally without sign-in when run inside an isolated terminal on the Computer itself.

Workspaces (v42 ws)

sh
v42 ws list [--all] [--discovered]
v42 ws show <workspace>
v42 ws create <computer> <path> [--name <name>] [--isolation]
v42 ws update <workspace> [--name <name>] [--path <path>] [--isolation] [--mirror-herdr <on|off>]
v42 ws archive <workspace> --yes
v42 ws move --index <index> <workspace>
v42 ws adopt <workspace> [--name <name>]
v42 ws storage <workspace> [--enable --yes]
v42 ws enter <workspace> [--stdio]
  • ws list: List the saved active Workspaces of the current Team.
    • --all: Include archived Workspaces.
    • --discovered: Include Workspaces discovered on Computers (such as Herdr workspaces) that have not been saved to the Team yet.
  • ws show <workspace>: Show one Workspace by ID or name (matching saved Workspaces first, then discovered, then archived).
  • ws create <computer> <path>: Save an absolute directory <path> on an online <computer> as a new Workspace.
    • --name <name>: Workspace name (at most 200 bytes; defaults to the last path component).
    • --isolation: Turn on terminal isolation so every new terminal starts in its own copy-on-write clone of <path>. The directory is checked for filesystem support first; once turned on, isolation cannot be turned off. Not available on Windows computers (isolation_windows_unsupported).
    • If a Workspace with the same name and directory already exists, fails with workspace_exists and returns the existing id in error.details.
  • ws update <workspace>: Change a saved Workspace's --name, --path (a new existing absolute directory on the same Computer), --isolation (turn on permanently), or --mirror-herdr <on|off> (whether tabs of a Herdr-bound Workspace with source_kind: "herdr" are mirrored into Herdr). Blocked while the directory is converting to deduplicated storage.
  • ws archive <workspace> --yes: Archive a saved Workspace (requires --yes; fails with confirmation_required otherwise). Its running terminals keep running, and files on disk are untouched. Archived Workspaces cannot be restored from the CLI.
  • ws move --index <index> <workspace>: Move a saved Workspace to a 1-based position in the v42 ws list sidebar order.
  • ws adopt <workspace> [--name <name>]: Save a discovered Workspace (from v42 ws list --discovered) to the Team.
  • ws storage <workspace> [--enable --yes]: Show the compression and deduplication state of a Workspace directory on an online macOS or Linux Computer (Windows computers report storage_windows_unsupported), or pass --enable --yes to start converting the directory (cannot be turned off once enabled).
  • ws enter <workspace> [--stdio]: Open a new terminal in <workspace> and attach to it immediately (see Terminals and agents).

Workspace memos (v42 memo)

Each Workspace holds up to 15 open memos alongside completed (--done) memos:

sh
v42 memo list <workspace> [--done]
v42 memo add <workspace> <text> [--visibility <private|team_read|team_write>]
v42 memo edit <workspace> <memo> [--text <text>] [--visibility <private|team_read|team_write>]
v42 memo done <workspace> <memo>
v42 memo undone <workspace> <memo>
v42 memo rm <workspace> <memo> --yes
v42 memo move --index <index> <workspace> <memo>
v42 memo send <workspace> <memo> <computer> <target> [--enter]

<memo> is either a memo ID or its 1-based index from v42 memo list (or v42 memo list --done for undone).

  • memo list <workspace>: List open memos in order (with 1-based index), or pass --done to list finished memos (most recently finished first). Other members' private memos are never shown.
  • memo add <workspace> <text>: Add a new memo at the top of the open list (<text> is up to 8192 bytes, trimmed, and may start with -). --visibility sets who can see and edit it:
    • private (default): Only you can see and edit it.
    • team_read: All Team members can read it; only you can edit it.
    • team_write: All Team members can read and edit it.
  • memo edit <workspace> <memo>: Change --text or --visibility (only the author can change visibility).
  • memo done / memo undone: Mark an open memo as finished, or reopen a finished memo.
  • memo rm <workspace> <memo> --yes: Permanently delete a memo (author only; requires --yes).
  • memo move --index <index> <workspace> <memo>: Move an open memo to a 1-based position in the open list.
  • memo send <workspace> <memo> <computer> <target> [--enter]: Type the memo's text into terminal <target> on <computer> (add --enter to press Enter afterward).

Terminal-isolation copies (v42 copy)

v42 copy works in two modes:

  1. Local mode (inside an isolated terminal on the Computer): When run inside <parent>/.<name>.v42-copies/<n>/work (or when V42_COPY is set), v42 copy talks directly to the local Vibe42 background service without needing v42 login or network access. For directory-level commands outside a copy, pass --root <path> (or run from the Workspace directory).
  2. Remote mode (from any signed-in machine over the network): Pass --workspace <workspace> (or --computer <computer> --root <absolute-path>) to target a Workspace directory on an online Computer. For commands that act on a single copy (save, versions, changes, diff, apply, push, delete, or single-copy status), also pass --copy <copy> with the copy number from v42 copy list (or its .v42-copies/<n> directory path).

Inspecting copies and support

sh
v42 copy list [--workspace <ws> | --computer <c> --root <path>]
v42 copy status [--workspace <ws> | --computer <c> --root <path>] [--copy <copy>]
v42 copy stats [--workspace <ws> | --computer <c> --root <path>]
v42 copy support [--workspace <ws> | --computer <c> --root <path>]
  • copy list: List all copies of a Workspace directory with their state (in_use, detached, preparing, …).
  • copy status: Show details for one copy (when inside a copy or when --copy <copy> is given), or list all copies of the Workspace directory.
  • copy stats: Show how much disk space the copies of a Workspace directory use.
  • copy support: Check whether a Workspace directory supports terminal isolation (.data.reason explains why if not).

Versions, changes, and diffs

sh
v42 copy save [-m <message>] [--workspace <ws>] [--copy <copy>]
v42 copy versions [--workspace <ws>] [--copy <copy>]
v42 copy changes [--from <id>] [--to <id>] [--workspace <ws>] [--copy <copy>]
v42 copy diff <path> [--from <ref>] [--to <ref>] [--workspace <ws>] [--copy <copy>]
  • copy save: Snapshot the copy's current files as a new version (-m / --message stores a note).
  • copy versions: List saved versions of the copy.
  • copy changes: List every path changed since the baseline (with status: pending, applied, or conflict), or compare two version IDs with --from and --to.
  • copy diff <path>: Show a unified diff for <path> (relative to the copy, as listed by changes). --from defaults to baseline and --to defaults to latest; either accepts baseline, latest, source (the current file in the main Workspace directory), or a version ID.

Applying, pushing, deleting, and index maintenance

sh
v42 copy apply [<paths>...] [--all] [--workspace <ws>] [--copy <copy>]
v42 copy push --branch <branch> [--workspace <ws>] [--copy <copy>]
v42 copy delete [--force] [--workspace <ws>] [--copy <copy>]
v42 copy rebuild-index [--workspace <ws> | --computer <c> --root <path>] --yes
v42 copy skill
  • copy apply: Write pending changes for <paths>... (or --all) back to the Workspace directory. copy apply lists the changes itself at the start of the call and verifies each path against that listing right before writing; if the copy changed in between, its status is changed_since_listing, and conflicts are never overwritten. A changes listing you ran earlier is not what it checks against, so review with copy diff right before applying.
  • copy push --branch <branch>: Push the copy's Git HEAD to <branch> in the main Workspace repository.
  • copy delete: Delete a copy and its working files. Refused with copy_in_use while a terminal window runs in it, and with copy_not_clean while unapplied changes remain unless --force is passed.
  • copy rebuild-index --yes: Discard and rebuild the version index of a Workspace directory (all copy version history is lost; requires --yes). Over the network, if rebuilding exceeds the 15-second reply limit (copy_timeout), check v42 copy list before retrying.
  • copy skill: Print the SKILL.md guide for coding agents running inside an isolated copy (see v42 CLI agent skill).