---
name: v42-cli
description: Use when operating Vibe42 from a shell: listing, starting, reading, sending to, waiting for or closing terminals on the user's Computers, arranging their tab and block layout, managing Workspaces, memos, isolated copies and files, taking screenshots of and controlling a Computer's desktop (mouse, keyboard, clipboard), or inspecting Computers and the Team.
---

# Driving Vibe42 with the v42 CLI

## Start here

`v42` is self-documenting. Before calling a command you have not used in this session, inspect its live help and treat `--help` as the authoritative reference for arguments, flags, and defaults:

```sh
v42 --help
v42 <group> --help
v42 <group> <command> --help
```

This skill gives common multi-step workflows and safety rules; `--help` has every flag.

Verify that the CLI is signed in and see the active Team before running commands:

```sh
v42 whoami
```

## Conventions

- **JSON envelope**: By default every command writes one JSON object to stdout on success, `{"ok":true,"data":...}`, and one JSON object to stderr on failure, `{"ok":false,"error":{"code":"...","message":"...","details":{...}}}`, with a non-zero exit code. Parse stdout with `jq` starting at `.data`. Exceptions: `term watch`, `desktop clipboard watch`, and `desktop control` stream newline-delimited JSON (NDJSON); `attach`, `term attach`, `ws enter`, and `term new --attach` stream raw PTY bytes; `desktop screenshot -o -` writes PNG bytes and `desktop stream` raw video; `skill` and `copy skill` print Markdown.
- **Identify yourself**: Always set `V42_AGENT_NAME=<your-agent-name>` (or pass `--agent-name`) so Team audit logs record which agent ran each command.
- **Targets and IDs**:
  - `<computer>` and `<workspace>` accept either a UUID or a name. Discover them with `v42 resources`, `v42 computer list`, or `v42 ws list`.
  - Terminal `<target>` accepts a window ID (`@3`), a pane ID (`%5`), or `<session>:@3` (as returned by `v42 term new` and `v42 term list`). Some commands (`term attach`, `attach`) also accept a session name.

| Exit code | Meaning |
|---|---|
| `0` | Success |
| `2` | Usage error, `confirmation_required` (`--yes` missing), or `terminal_busy` (`--force` missing) |
| `3` | Not signed in or session expired |
| `4` | Permission denied |
| `5` | Local storage or I/O failure |
| `6` | Invalid request, not found, or conflict |
| `7` | Network or remote failure, or timeout |
| `8` | `v42 term wait` timed out (`wait_timeout`) |
| `130` / `143` | Interrupted (`SIGINT` / `SIGTERM`) |

## Workflows

### 1. Find and close idle terminals

A terminal is idle only when every pane's foreground is at its shell prompt (`idle`) and no agent is `working`, `blocked`, or in `error`. Terminals with `unknown` state count as busy.

1. List idle terminals across the Team or on one Computer:
   ```sh
   v42 term list my-mac --idle
   ```
2. Preview what `--idle` would close (optionally scoped to one Workspace):
   ```sh
   v42 term close my-mac --idle --workspace api --dry-run
   ```
3. Close those idle terminals (windows mirrored from Herdr or external tmux sessions are skipped with `external_source`):
   ```sh
   v42 term close my-mac --idle --workspace api
   ```
4. Or close specific idle targets by ID:
   ```sh
   v42 term close my-mac @12 @15
   ```

### 2. Start a coding agent in a Workspace and wait for its result

1. Check available agent launchers and catalog IDs:
   ```sh
   v42 agents list
   ```
2. Start a terminal in the Workspace using a configured `--launcher` (or a catalog `--agent` / custom `--command`) and capture its window ID:
   ```sh
   win=$(V42_AGENT_NAME=claude v42 term new my-mac --workspace api --launcher claude-code | jq -r '.data.window_id')
   ```
3. Wait until the agent finishes its turn instead of polling in a loop. `--until done` keeps waiting while the agent is blocked on a confirmation or in error, so on exit `8` check `v42 term status` (`agent.state`) before waiting again:
   ```sh
   v42 term wait my-mac "$win" --until done --timeout 600
   ```
   Other `--until` states: `idle`, `blocked`, `error`, `working`, `gone`, or `output` (with optional `--match <regex>`). Exit code `8` means the timeout elapsed first.
4. Read the visible screen (and recent scrollback if needed):
   ```sh
   v42 term read my-mac "$win" --history 80
   ```

### 3. Send input and read the screen

1. Type text and press Enter in a terminal without disturbing other viewers:
   ```sh
   v42 term send my-mac @12 "bun test" --enter
   ```
2. Send special keys or key chords (`ctrl+c`, `escape`, `up`, `shift+tab`):
   ```sh
   v42 term send my-mac @12 --key ctrl+c
   ```
3. Send multi-line input safely from stdin with bracketed paste:
   ```sh
   printf ' Explain the failing test\nand propose a minimal fix.\n' | v42 term send my-mac @12 --stdin --paste --enter
   ```
4. Read the current screen (or add `--history <lines>` / `--all`):
   ```sh
   v42 term read my-mac @12 --history 50
   ```

### 4. React to terminal changes

Stream live terminal events as NDJSON (`ready`, `terminal_added`, `terminal_removed`, `renamed`, `workspace_changed`, `agent_status`, `foreground`, `unavailable`, `stopped`):

```sh
v42 term watch my-mac --workspace api --count 10 --timeout 120
```

### 5. Arrange the tab and block layout

Every Workspace and Computer has a per-user layout synced live with the Vibe42 apps. Pass `--workspace <ws>` or `--computer <c>` to select the container.

1. Inspect the current tabs and blocks:
   ```sh
   v42 layout show --workspace api
   ```
2. Create an empty tab or open a new terminal block beside an existing block:
   ```sh
   v42 tab new --workspace api --title "Backend"
   v42 block new terminal --workspace api --tab "Backend"
   v42 block new terminal --workspace api --tab "Backend" --beside 1 --side right
   ```
3. Apply an arrangement preset (`columns`, `rows`, `grid`, `main-side`, `main-stack`) to a tab:
   ```sh
   v42 tab arrange --workspace api "Backend" grid
   ```
4. Float a block over the tab, dock it back into splits, or close it:
   ```sh
   v42 block float --workspace api --tab "Backend" 2 --rect 0.2,0.15,0.6,0.7
   v42 block dock --workspace api --tab "Backend" 2 --end
   v42 block close --workspace api --tab "Backend" 2
   ```

### 6. Work with files on a Computer

Remote paths use `<computer>:/absolute/path`; paths without a prefix are local.

1. Inspect and search remote directories:
   ```sh
   v42 ls -la my-mac:/Users/me/api
   v42 stat my-mac:/Users/me/api/package.json
   v42 find my-mac:/Users/me/api "schema" --limit 50
   ```
2. Create directories and copy or sync files:
   ```sh
   v42 mkdir -p my-mac:/Users/me/api/build/artifacts
   v42 cp -r ./dist my-mac:/Users/me/api/build/artifacts
   v42 sync my-mac:/Users/me/api/dist ./dist
   ```
   `sync` keeps extra destination files unless `--delete` is passed; interrupted transfers resume automatically unless `--restart` is passed.
3. Delete files or directories (deleting a directory with `-r` requires `--yes`; without `--yes` it exits with `confirmation_required` and reports how many entries would be deleted):
   ```sh
   v42 rm my-mac:/Users/me/api/build/tmp.log
   v42 rm -r my-mac:/Users/me/api/build/artifacts
   v42 rm -r my-mac:/Users/me/api/build/artifacts --yes
   ```

### 7. Isolated copies from outside or inside a terminal

When a Workspace uses terminal isolation, each terminal gets a copy-on-write clone `<parent>/.<name>.v42-copies/<n>/work`.

1. From any machine over the network, pass `--workspace <ws>` (or `--computer <c> --root <path>`) and `--copy <n>` to inspect or manage copies:
   ```sh
   v42 copy list --workspace api
   v42 copy status --workspace api --copy 1
   v42 copy changes --workspace api --copy 1
   v42 copy diff src/index.ts --workspace api --copy 1 --from source
   v42 copy save -m "Checkpoint" --workspace api --copy 1
   ```
2. When the user asks to write pending changes back or push a Git branch:
   ```sh
   v42 copy apply --all --workspace api --copy 1
   v42 copy push --branch agent/fix-auth --workspace api --copy 1
   ```
3. If you are running *inside* an isolated terminal (`V42_COPY` is set), omit `--workspace` and `--copy`, and read the dedicated copy skill with `v42 copy skill`.

### 8. Workspaces and memos

1. List, inspect, create, or update Workspaces:
   ```sh
   v42 ws list
   v42 ws show api
   v42 ws create my-mac /Users/me/api --name api
   v42 ws update api --name "api-service"
   ```
2. Read, add, send, and complete Workspace memos:
   ```sh
   v42 memo list api
   v42 memo add api "Run integration suite before release" --visibility team_write
   v42 memo send api 1 my-mac @12 --enter
   v42 memo done api 1
   ```

### 9. See and control a Computer's desktop

Needs a Computer whose `featureset` contains `desktop.v1` (`v42 computer show my-mac`). Every session wakes the display; input needs remote control to be allowed there (`desktop_view_only` otherwise).

1. Look first. Coordinates are native pixels of the **display** (`.data.display.width/height`), not of the image, which is often smaller:
   ```sh
   v42 desktop screenshot my-mac -o /tmp/screen.png | jq '.data | {width, height, display}'
   ```
   Scale a point you found in the image by `display.width / width` (and the same for height).
2. Act, then look again to check the effect. Prefer `--window <id>` (from `v42 desktop windows` or `v42 desktop launch`) for `key`, `type` and `clipboard copy`, so input reaches that window instead of whatever has focus; with `--window`, pointer coordinates are native pixels of the window's capture area (`.data.window.width/height` of `screenshot --window`):
   ```sh
   v42 desktop click my-mac 1520 830
   v42 desktop type my-mac "hello world" --window 4711
   v42 desktop key my-mac cmd+s --window 4711   # combos: cmd/ctrl/alt/shift + a key name or DOM code
   v42 desktop scroll my-mac --at 1520 830 --dy 600
   v42 desktop screenshot my-mac -o /tmp/screen.png
   ```
   `type` sends line breaks as Shift+Enter; press Enter with `v42 desktop key my-mac enter`. Each input command waits an estimated time for the Computer to apply it, then disconnects, and the Computer drops input it has not applied yet: on a slow Computer (a virtual machine, a busy host) a command can report success while part of its text or keys never arrived. Check the result with a screenshot or `clipboard copy`, and use `desktop control` for long text or many steps.
3. For many steps, keep one session open with `desktop control` (one JSON request per stdin line, one answer per stdout line):
   ```sh
   printf '%s\n' '{"id":1,"op":"click","x":1520,"y":830}' '{"id":2,"op":"type","text":"hello"}' \
     '{"id":3,"op":"screenshot","path":"/tmp/after.png"}' '{"id":4,"op":"close"}' | v42 desktop control my-mac
   ```
4. Read text through the clipboard: select it, then `v42 desktop clipboard copy my-mac --window 4711` presses the copy shortcut and returns `.data.text`; `v42 desktop clipboard set my-mac "text"` and `v42 desktop key my-mac cmd+v` paste.
5. List windows and apps with `v42 desktop windows` / `v42 desktop apps`; capture one window with `--window <id>` (it is brought to the front, and coordinates then refer to its capture area).

## Safety rules

- **Never pass `--force` or `--yes` unprompted**: Only use `--force` or `--yes` when the user explicitly asked for that destructive action or when cleaning up a resource you created yourself in the current task.
- **Run `--dry-run` or preview first**: Use `--dry-run` on `term close --idle`, `computer cleanup`, and `device cleanup`, and run `rm -r` without `--yes` first to see the entry count before confirming.
- **Leave other terminals alone**: Do not close, rename, or move terminals you did not start unless the user asked you to.
- **Respect busy and unknown state**: `term close`, `block close`, and `tab close` refuse busy or unknown terminals on purpose (`terminal_busy`, exit 2). Do not bypass that with `--force` without checking what is running (`term status`, `term read`) and getting user approval.
- **Protected paths**: `v42 rm -r` always refuses the filesystem root, the home directory, and its parent directories.
- **Desktop input acts on a real screen**: Take a screenshot before clicking or typing, never type passwords or secrets with `desktop type` (`desktop unlock` reads the password from stdin only), and do not `unlock` a Computer unless the user asked you to.
- **Wait instead of polling**: Use `v42 term wait` or `v42 term watch` rather than `sleep` loops around `term read` or `term status`.
