# CLI reference

> Every prized command, flag, JSON shape, and exit code, on macOS, Linux, and Windows.

URL: https://prized.dev/docs/cli

## Commands [#commands]

Add `--help` to any command. With `--json`, every non-interactive command prints exactly one object, `{"ok": true, ...}` with the payload inline on success; failures and exit codes are under [For agents and scripts](#for-agents-and-scripts).

`prized help` lists every command with a line each, and `prized help <command>` (or `prized <command> --help`) prints one command's flags and examples.

### Sign in and set up [#sign-in-and-set-up]

`prized login` opens the dashboard to make an API key for this machine, stores it in `~/.config/prized` (`%LOCALAPPDATA%\Prized` on Windows), sets up your SSH identity, and registers this machine's device key ([Claude Desktop remote](https://prized.dev/docs/claude-desktop)); with no config yet and exactly one box on the account, it also connects that box. Flags: `--token` (an API key from the dashboard or a single-use install token; the only form `--json` accepts), `--token-stdin`, `--url`. JSON: `{"ok": true, "email", "workspace", "boxes", "box", "url"}`, plus `keyExpiresAt` for a dashboard key that expires. The key `prized login` makes never expires while the machine uses it; after 180 days unused, commands exit 8 with `this API key has expired` and you sign in again ([When a key expires](https://prized.dev/docs/workspaces#when-a-key-expires)).

Your saved sign-in is tied to the control-plane address you authenticated with. Changing `[controlplane].url`, `--config`, or `PRIZED_CONFIG` does not authorize sending it to another address. If the CLI reports a different control-plane origin, check the URL before signing in there; older saved sign-ins work only with Prized's production service until you sign in again.

`prized start` is what [`npx prized`](https://prized.dev/docs/terminal-signup) runs: the sign-up in this terminal, a box, where you work, and this machine set up. Already signed in, it points you to `prized setup`.

`prized setup [PATH]` sets this machine up for your box and is safe to re-run: a repairing health check, the project to sync, your environment, the agents, and a detached session. `prized setup auto` skips the auto-or-manual question ([Quickstart](https://prized.dev/docs/quickstart#4-set-up)).

| Flag                                                                 | Meaning                                                                                                                    |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `--project`, `--no-project`                                          | The project to sync (a name or a path), or none.                                                                           |
| `--copy`, `--copy-once`, `--clone`                                   | Copy and keep syncing, copy once with no sync, or `git clone` on the box; the default syncs in place.                      |
| `--merge`                                                            | Merge into an existing folder on the box instead of refusing.                                                              |
| `--env`, `--env-secrets`, `--env-data`, `--no-env`                   | The [environment](https://prized.dev/docs/environment) groups to bring; data is never covered by auto or `-y`.                               |
| `--env-workers N`                                                    | Environment items installed at once (default 8); `1` installs them in order.                                               |
| `--agent NAME`, `--no-agents`, `--save`                              | Agents to hand off (`claude`, `codex`, `cursor`, `chatgpt`); `--save` records the pick.                                    |
| `--gh`, `--no-gh`, `--install-cursor`                                | The GitHub token and git identity; Cursor's installer.                                                                     |
| `--start`, `--no-start`, `--attach`, `--no-attach`, `--session NAME` | The picked agent's detached session; `--attach` opens it here instead of printing the reattach command.                    |
| `--box NAME`                                                         | The box to set up; one other than the default gets its own config and daemon ([Several boxes](https://prized.dev/docs/boxes#several-boxes)). |
| `--dry-run`, `--non-interactive`                                     | Print what a run would do and change nothing; never prompt.                                                                |
| `--signup ID`                                                        | Finish what a [terminal sign-up](https://prized.dev/docs/terminal-signup) started (its box, mode, and app); `npx prized` passes it.          |

JSON: `{"ok": true, "steps": [{"id", "status": "done|skipped|failed", "duration"}], "state": "READY|DEGRADED", "env"}`.

`prized init` adopts a box on your account (config, SSH stanza, daemon); `login` and `setup` run it for you. Flags: `--box NAME` (another box, with its own `boxes/<name>.toml` and daemon), `--force` (make it the default instead, rewriting `config.toml` after a backup; refused for a box with its own file), `--user NAME`, `--no-daemon`, `--non-interactive`.

`prized env scan|plan|migrate` runs the environment step alone: list what your machine has, print the questions, apply them. Flags: `--project PATH`, `--advisor`/`--no-advisor`, `--non-interactive` ([Bring your environment](https://prized.dev/docs/environment)).

### Box lifecycle [#box-lifecycle]

Every action also works from the [dashboard](https://prized.dev/dashboard); what each does is on [Boxes](https://prized.dev/docs/boxes).

* **Naming a box.** `BOX` is a hostname (`mango`), a box id, `current` (the last box this machine created), or `self` (the box the command runs on); omitted, it is the box you set up. An unknown name exits 5 and lists your boxes.
* **Sizes.** Tier id or public name: `nano` (Nano), `micro` (Micro), `lite` (Extra Small), `flow` (Small), `pro` (Medium), `max` (Large), `ultra` (Extra Large); prices on [Billing](https://prized.dev/docs/billing). Until a plan is live, the [free credit](https://prized.dev/docs/billing#free-credit) allows Nano through Small, one box at a time: a bigger size exits 5, a second box exits 6.
* **Windows.** `--ttl` and `--auto-pause` take a duration with a unit: `45m`, `4h`, `1h30m`, `2d`.

#### box new [#box-new]

```bash
prized box new                         # a fruit name, the size your balance runs comfortably
prized box new mango --size Small --ttl 4h --auto-pause 45m --wait
```

Returns as soon as the control plane has the box, which becomes `current`; boot times are on [Boxes](https://prized.dev/docs/boxes).

| Flag                  | Meaning                                                                                                                                                                               |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NAME`                | Lowercase letters, digits, and hyphens, starting and ending with a letter or digit, up to 32 characters.                                                                              |
| `--tier`, `--size`    | The size; either name works.                                                                                                                                                          |
| `--ttl WINDOW`        | A [pause deadline](https://prized.dev/docs/boxes#pause-deadline), 5m to 30d from now.                                                                                                                   |
| `--auto-pause WINDOW` | [Idle auto-pause](https://prized.dev/docs/boxes#auto-pause), 30m to 7d; refused on the [free credit](https://prized.dev/docs/billing#free-credit).                                                                        |
| `--environment NAME`  | Apply a saved [environment](https://prized.dev/docs/boxes#environments) at first boot, by name or `env_` id.                                                                                            |
| `--from-snapshot ID`  | Restore a [snapshot](https://prized.dev/docs/boxes#snapshots) into the new box, at the snapshot's size.                                                                                                 |
| `--region REGION`     | Where the box starts, by AWS id or name ([Regions](https://prized.dev/docs/machines#regions)); `us-west-2` (Oregon) by default. With `--from-snapshot`, a [move](https://prized.dev/docs/boxes#regions) after first boot. |
| `--wait`              | Poll until the box is running (5 minute budget), then print the `prized ssh` line.                                                                                                    |

Exit 6 (`CONFLICT`): a taken name, the box count, or a balance that cannot run the box. Exit 5: a size not on your plan, a bad name, or a window out of bounds.

#### The rest of the box group [#the-rest-of-the-box-group]

Each prints `{"ok": true, "box": {...}}` with [the box object](#the-box-object) unless noted.

| Command                                            | What it does                                                                                                                                                                     |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `box ls [--all] [--filter STATES]`                 | NAME, STATE, SIZE, REGION, AUTO-PAUSE, PAUSE-AT, CREATED; `--all` adds terminated boxes. JSON: `{"boxes"}`.                                                                      |
| `box info BOX`                                     | State, size, region, tunnel IP, login user, disk, pause settings, last vitals, last eight events. JSON adds `events` and `pausesSurvived`.                                       |
| `box pause BOX`, `box resume BOX [--wait]`         | Aliases `stop`, `wake` ([Pause and resume](https://prized.dev/docs/boxes#pause-and-resume)); `--wait` polls until running. Idempotent; a resume the balance cannot cover exits 5.                  |
| `box delete BOX [-y]`                              | Permanent: machine and disk gone. Asks you to type the name; `--json` needs `-y` (exit 2 without).                                                                               |
| `box rebind BOX`                                   | Binds a name's ssh alias to the box that has the name now. After a box is recreated or its freed name taken, `ssh BOX` and the prized commands refuse the name until you rebind. |
| `box resize BOX SIZE` (or `prized resize SIZE`)    | Restarts the box at the new size ([Resize](https://prized.dev/docs/boxes#resize)). Refusals exit 5. JSON adds `from`, `to`.                                                                        |
| `box move BOX REGION`                              | Moves the box ([Regions](https://prized.dev/docs/boxes#regions)); `desiredRegion` is set at once, `region` changes when the move lands.                                                            |
| `box extend BOX --ttl WINDOW \| --no-deadline`     | Sets, replaces, or clears the [pause deadline](https://prized.dev/docs/boxes#pause-deadline); setting one needs a running box (exit 5), clearing always works.                                     |
| `box auto-pause BOX WINDOW\|off`                   | Sets the [idle window](https://prized.dev/docs/boxes#auto-pause) (30m to 7d, or bare minutes) or switches it off; a window is refused on the [free credit](https://prized.dev/docs/billing#free-credit).             |
| `box auto-snapshot BOX --every 6h\|off [--keep 5]` | Sets or clears a [snapshot schedule](https://prized.dev/docs/snapshots#automatic-snapshots): every 1 to 168 hours, keeping 1 to 10.                                                                |

#### The box object [#the-box-object]

```json
{
  "id": "5d0a…", "hostname": "mango",
  "observedState": "running", "desiredState": "running",
  "tier": "flow", "instanceType": "m6a.xlarge",
  "region": "us-west-2", "desiredRegion": "us-west-2",
  "loginUser": "hudson", "boxIp": "10.77.3.1", "diskGb": 100,
  "autoPauseMin": 45, "pauseAt": "2026-09-01T18:30:00Z",
  "lastHeartbeatAt": "2026-09-01T15:17:52Z", "createdAt": "2026-08-29T12:00:00Z",
  "runningSince": "2026-09-01T09:02:11Z",
  "vitals": {"cpu_pct": 12, "mem_pct": 41, "disk_pct": 63, "idle_for_sec": 720}
}
```

`autoPauseMin`, `pauseAt`, `diskGb`, `lastHeartbeatAt`, and `vitals` are `null` when unset or unknown. `runningSince` is when the box last started, resumed or rebooted; it is `null` unless the box is running or degraded, and `box ls --json` and `box info --json` carry it. Timestamps are RFC 3339 UTC.

#### Terminal dashboard [#terminal-dashboard]

```bash
prized dashboard
```

A full-screen view of your boxes in the terminal (aliases `dash`, `top`; `prized dashboard BOX` selects that box first): every box with its state and vitals (yours first, your teammates' folded under Team) and, for the one you select, live CPU, memory and network charts, its processes, ports, sessions, disks and recent events. A paused box shows its history and is never woken by selecting it. Click a box, a tab, or a button at the bottom, or use the keys:

| Key                               | What it does                                                                                                                                             |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `↑` `↓` (or `j` `k`)              | Select a box                                                                                                                                             |
| `Enter` (or `s`, or double-click) | Open a shell on the box (`prized ssh`); on the Sessions tab, attach the selected session. A paused box asks before it wakes. Exit the shell to come back |
| `p`, `r`                          | Pause (after you confirm) or resume the box                                                                                                              |
| `o`                               | Open the box in the web dashboard                                                                                                                        |
| `1` `2` `3`                       | Chart history: 15 minutes, 1 hour, 24 hours                                                                                                              |
| `/`                               | Filter boxes by name                                                                                                                                     |
| `t`                               | Show or hide your teammates' boxes                                                                                                                       |
| `?`                               | Every key                                                                                                                                                |
| `q`                               | Quit                                                                                                                                                     |

Shell actions stay bound to the selected box’s ID, including after a wake confirmation. If that box was deleted and another box reuses its name, the shell is refused instead of connecting to the replacement. Refresh the fleet and deliberately select the box you want.

It needs a terminal at least 60 columns by 15 rows; `box ls` is the plain list for scripts.

### Snapshots [#snapshots]

| Command                                                                   | What it does                                                                    |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `prized snapshot create BOX [--name NAME] [--description TEXT]`           | Snapshot a disk without stopping the box.                                       |
| `snapshot ls [--box BOX] [--kind KIND]`                                   | List snapshots.                                                                 |
| `snapshot restore SNAPSHOT [--name NAME] [--tier SHAPE]`                  | Launch a new box from a snapshot or template.                                   |
| `snapshot delete SNAPSHOT`                                                | Retire a snapshot.                                                              |
| `snapshot template SNAPSHOT NAME`, `snapshot untemplate NAME`             | Name a snapshot (or a box, snapshotting it first) as a template; drop the name. |
| `prized fork BOX [--name NAME] [--tier SHAPE] [--keep-snapshot] [--wait]` | A new box from a copy of a running box's disk.                                  |

Behaviour, kinds, and limits: [Snapshots](https://prized.dev/docs/snapshots).

### Environments [#environments]

`prized environments` (alias `envs`) manages what a new box inherits: `ls`, `info`, `new`, `default`, `rm`, `set`, `set-var`/`rm-var`, `set-file`/`rm-file`, `add-repo`/`rm-repo`, `upgrade`. Every command and its JSON: [Environments](https://prized.dev/docs/environments).

### Secrets [#secrets]

`prized secrets` controls who may use a workspace secret and shows what it was spent on; values are set and rotated in the dashboard only ([Scoped secrets](https://prized.dev/docs/teams#scoped-secrets)).

| Command                                           | What it does                                                                                                                        |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `secrets ls [--box BOX]`                          | NAME, SCOPE, HOSTS, MOUNTS, ROTATED; with `--box`, only what that box may mount.                                                    |
| `secrets grant NAME --box BOX \| --member EMAIL`  | Make the secret available to one box, or to every box a member owns; the first grant narrows a workspace-wide secret to its grants. |
| `secrets revoke NAME --box BOX \| --member EMAIL` | Take a grant back; the box loses the secret within seconds. Revoking the last grant makes the secret workspace-wide again.          |
| `secrets grants NAME`                             | Who has it: KIND, TO, SINCE.                                                                                                        |
| `secrets usage NAME`                              | Which boxes spent it against which hosts: BOX, HOST, FIRST, LAST, COUNT (a floor).                                                  |

`grant` and `revoke` take exactly one of `--box` and `--member` (exit 2 otherwise); an unknown secret, box, member, or grant exits 5; a `409` exits 6. JSON mirrors the columns.

### Connect [#connect]

`prized ssh [BOX] [SESSION] [-- CMD...]` attaches to a persistent tmux session (waking a suspended box) and forwards a non-default box's ports while connected ([Sessions](https://prized.dev/docs/sessions)). Flags: `-s, --session NAME` (default `main`), `--ls`, `--kill NAME` (asks unless `-y`), `--raw` (no tmux), `--no-forward`, `--no-drop-upload`, `--no-clipboard` ([Copy out](https://prized.dev/docs/sessions#copy-out)). With `-- CMD` it runs that one command instead, sharing the box's connection the way `prized exec` does.

Interactive forms reject `--json` (exit 2); once connected, the exit code is ssh's or the remote command's. JSON: `--ls` `{"sessions": [{"name", "windows", "created", "attached"}]}`, `--kill` `{"killed"}`.

Every command that uses SSH runs the OpenSSH client from the system directories (`/usr/bin`, or `System32\OpenSSH` on Windows), never one on `PATH`; name another with `bin = "/path/to/ssh"` under `[ssh]` in the config.

`prized mosh [BOX] [SESSION]` is the same session over mosh (installed locally; not on Windows yet), with `-s`, `--raw`, `--no-forward`, `--no-drop-upload`. `prized herdr [BOX] [SESSION]` lands in [herdr](https://prized.dev/docs/herdr) instead of tmux, installing it on the box the first time. `prized up` starts the box, reconnects everything from cold, and prints the `status` block; `--resume` resumes paused syncs, `--wait-timeout` (default `5m`) bounds the wait. `prized proxy BOX PORT[:LOCALPORT]` forwards one box port to localhost until interrupted.

### Run commands and files [#run-commands-and-files]

`prized exec [BOX] [flags] -- CMD...` runs one command on the box and exits with its code: `--cwd`, `--timeout`, and `--env K=V` shape the run, `--detach` returns an id, and `--status ID`, `--ps`, `--kill ID` inspect or stop detached runs without waking a paused box. Runs back to back share one connection to the box, so after the first, each one starts without a new handshake. JSON: `{"ok": true, "exitCode", "stdout", "stderr", "commandId"}`. `prized exec history [BOX]` lists what ran and `prized exec logs [BOX] ID [--stderr] [--offset N] [--follow]` prints one command's output, from Prized rather than the box, so both work while it is paused ([Command history](https://prized.dev/docs/exec#command-history)); if the live-log address is not trusted, `--follow` says so and prints retained history instead. Terminal display neutralizes control characters while file and pipe exports keep exact bytes. `--delete ID` and `--delete-all` remove records. `prized cp [-r] SRC DST` copies files scp-style: `box:path` is a path on a box, `:path` one on your box.

Both are on [Run commands and files](https://prized.dev/docs/exec), and both report what they did (never output or contents) to the [audit log](https://prized.dev/docs/teams#audit-log) as a **reported** row.

### Desktop [#desktop]

`prized desktop [BOX]` opens the box's desktop in the dashboard and forwards its VNC port until interrupted; `--no-open` prints the `vnc://` address and password, `--stop` ends it. `prized browser [BOX]` does the same with one Chrome window (`--profile`, `--url`). Starting either reports a `desktop.start` audit row (mode and profile, never the password); see [Desktop](https://prized.dev/docs/desktop).

### Sync [#sync]

`prized sync add PROJECT | add --local PATH` mirrors a folder between the box and this machine ([Sync](https://prized.dev/docs/sync)). Flags: `--local PATH` (your own folder, in place, instead of `~/Prized/<name>`), `--remote PATH` (default `~/code/<name>`), `--name NAME`, `--prefer box|mac` (default `box`), `--mode MODE` (default `two-way-resolved`), `--ignore` and `--unignore`, `--create` (make the remote folder), `--paused`, `--merge` (allow a non-empty local folder).

`prized sync` (or `sync ls`) lists sessions with state and problems; `pause`, `resume`, and `flush` take a name or `--all` (`flush --timeout`, default `60s`); `repair NAME` recreates a halted session; `rm NAME` removes one (`--delete-local`, `--delete-box` also move the files aside). JSON: `add` `{"project"}`; `ls` `{"projects", "degraded"?}`; `repair` `{"repaired"}`; `rm` `{"removed", "files": "keep|trash_local|trash_box"}`.

### Mount [#mount]

`prized mount [BOX]` mounts a box in Finder from a background process and returns, macOS only ([Mount](https://prized.dev/docs/mount)); `-f, --foreground` serves from the terminal until interrupted. Flags: `--dir PATH` (default the home directory), `--at PATH` (default `~/Prized/boxes/<box>`), `--read-only`, `--mount-opt OPTS`, `--no-open`.

`prized unmount [BOX]` stops a mount, background or foreground. JSON: mount `{"box", "mountpoint", "pid", "detached", "log"}`, plus `"already": true` for a box already mounted (the call then opens the folder); unmount `{"box", "mountpoint", "unmounted"}`.

### Ports [#ports]

`prized ports ls` lists the box's listeners and their mirror state; `prized ports toggle PORT` switches one mirror on or off ([Ports](https://prized.dev/docs/ports)). JSON: `ls` `{"ports": [{"port", "label", "process", "state", "reason"}]}`; `toggle` `{"port", "state", "reason"}`.

`prized ports share PORT` prints a link sharing the port with your workspace (the same link again for a shared port); `--anyone` makes a link anyone who has it can open, shown once, and `--public` one anyone at all can open (owner only); `--expires 7d` sets how long either lasts, 5 minutes to 30 days, 7 days by default. `--anyone` or `--public` on a port shared with another audience replaces its link; with neither flag, a shared port prints its existing link. `prized ports share` alone lists the box's shared ports; `prized ports unshare PORT` stops sharing ([Share a port](https://prized.dev/docs/ports#share-a-port)). A bad port or flag exits 2 before any call; a port that is not shared, or a link Prized refuses (the free credit, the workspace's limit, your role), exits 5 with the reason. JSON: `share PORT` `{"share": {"id", "boxId", "hostname", "port", "slug", "access", "url", "origin", "expiresAt", "createdBy", "createdAt", "openCount", "lastOpenedAt"}, "created", "replaced"}`; `share` `{"enabled", "linksEnabled", "shares": [...]}`; `unshare` `{"share", "revoked": true}`.

### Agents [#agents]

| Command                              | What it does                                                                                                                                                                                                            |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prized agents ls`                   | One row per coding agent: installed and signed in here and on the box, MCP servers, where it runs.                                                                                                                      |
| `prized agents handoff [AGENT...]`   | Copy the named agents' sign-in and MCP config to the box (`--gh`, `--install-cursor`); a Codex ChatGPT sign-in does not travel, so the box signs in through your browser instead and the result shows in your terminal. |
| `prized agents run AGENT`            | Start an agent detached in a tmux session (`--session`, `--dir`, `--attach`, `-- ARGS`); `opencode` and `pi` are installed on the box first if needed (JSON adds `installed`).                                          |
| `prized agent upgrade [--version V]` | Upgrade the box agent, which normally updates itself.                                                                                                                                                                   |

See [Agents](https://prized.dev/docs/agents).

### Prompt an agent remotely [#prompt-an-agent-remotely]

`prized prompt [BOX] --provider claude|codex|opencode|pi [flags] TEXT` runs the box's coding agent headless on one prompt (`-` reads it from stdin) and follows its events until it answers. Flags: `--model` (`amazon-bedrock/ID`, `openrouter/ID` or `deepseek/ID` picks a backend), `--effort low|medium|high`, `--cwd`, `--continue` (resume the provider's newest session), `--queue` (run after the run in progress), `--detach` (start and return the id), `--auto` (no approvals). OpenCode and pi are installed on the box at their first prompt; a failed install exits 5 with the reason.

`prized prompt models [--provider P]` lists known `--model` values with their backend and efforts, without touching a box; JSON `{"models": [{provider, id, backend, efforts, note}], "backends"}`.

Each prompt is a turn of a conversation, and conversations run in parallel up to the box's limit: `--new` starts one (the default), `--continue` takes the provider's newest, `--conversation ID` a given one (`--provider` is required here too; box-side metadata never chooses it), and `--queue` waits behind the conversation's turn in progress. `prized prompt conversations [BOX]` lists conversations; `prized prompt ls [BOX] [--conversation ID]` lists runs; `prized events [BOX] [--run ID | --conversation ID] [--follow] [--after N]` shows a run, or follows every run in progress; `prized interrupt [BOX] [--run ID | --conversation ID]` stops every run in progress, or the one named. Only `prompt` wakes a box. Every provider and backend works in conversations alike. Exit: 0 when the run ends cleanly, 1 when it failed (its last verdict an error) or was interrupted, 6 when the conversation has a turn in progress or the box is at its limit, 130 on Ctrl-C.

JSON: `prompt --json` prints the started run and does not follow; `prompt --jsonl` and `events --jsonl` print one normalized event per line; `prompt conversations` `{"conversations", "running", "limit"}`; `prompt ls` `{"runs", "active"}`; `events` `{"run", "events", "next", "finished"}`; `interrupt` `{"interrupted", "id", "wasRunning", "signal"}`. Shapes: [Prompt an agent remotely](https://prized.dev/docs/remote-agents).

### Team [#team]

`prized team status` is what the team is doing now, `prized team log` what happened; neither needs a box config ([Teams](https://prized.dev/docs/teams)).

```bash
prized team status
prized team log --since 7d --kind exec,prompt --member ana@acme.com
```

`team status` prints every live box (BOX, OWNER, STATE, IDLE, SESSIONS, SPEND TODAY), every member (MEMBER, ROLE, BOXES, SESSIONS, SPEND (CYCLE), LAST ACTIVE), and a totals line; a contractor gets their own boxes. JSON: the fields of [`GET /api/v1/team/status`](https://prized.dev/docs/api#team).

`team log` prints the [audit log](https://prized.dev/docs/teams#audit-log) as TIME, MEMBER, KIND, BOX, DETAIL, ORIGIN (`server` or `reported`); contractors exit 5. Flags: `--since WINDOW` (default `24h`), `--kind KINDS`, `--box BOX`, `--member EMAIL`, `--limit N` (default 100, at most 1000). JSON: `{"events": [{"id", "at", "kind", "origin", "actorKind", "actorUserId", "actorTokenId", "boxId", "detail"}], "nextBefore"}`.

### Health and updates [#health-and-updates]

`prized status` is box, sync, ports, and daemon state at a glance; `--watch 2s` keeps it open. JSON: `{"box", "sync", "ports", "daemon", "update": {"available"}}`; `box.transport_path` is `udp`, `relay` (the Prized relay over HTTPS), `ws` (the box's own port 443), `probing` while it looks for a way through, or empty while the tunnel is down. An unreachable box prints `"ok": false` and exits 3.

`prized doctor` is the full health check: it applies safe repairs by default, marks them `(fixed)`, and prints only checks that failed, warned, or were fixed ([Troubleshooting](https://prized.dev/docs/troubleshooting)). Flags: `--no-fix`, `--strict` (warnings fail), `-v` (every check), `--bundle` (a diagnostics tarball; nothing leaves your machine); for the agent token and host key, `--rotate-token`, `--fetch-token`, `--forget-hostkey`, `--pin-hostkey K`. JSON: `{"summary": {"pass", "warn", "fail", "skip", "fixed"}, "checks": [{"id", "status", "detail", "hint", "fixed"}]}`.

| Command                                                                            | What it does                                                                                                                                                                               |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `prized version` (or `prized --version`)                                           | Client, daemon, and agent versions for the box in use (`--box NAME` for another).                                                                                                          |
| `prized update`                                                                    | Update prized and the daemon in place from signed releases (`--check` only reports, `--channel` picks one); it also runs by itself ([Updates](#updates)).                                  |
| `prized daemon install`, `uninstall`, `start`, `stop`, `restart`, `status`, `logs` | Manage the daemon of the box in use: launchd on macOS, systemd --user on Linux, a Scheduled Task on [Windows](#windows).                                                                   |
| `prized daemon proxy`                                                              | Show the daemon's proxy (PAC locations are omitted).                                                                                                                                       |
| `prized daemon proxy set [URL]`, `prized daemon proxy clear`                       | Change it. `set` defaults to your shell's `HTTPS_PROXY`, refuses (keeping the old proxy) when there is none it can use, and records a proxy that does not answer from here with a warning. |
| `prized mutagen ensure`                                                            | Fetch Prized's managed Mutagen; the installer, `setup`, and `doctor` run it for you.                                                                                                       |
| `prized ops status OP [--wait]`                                                    | Print or poll a deletion operation (`dop_…`) the API returned ([Deletion operations](https://prized.dev/docs/data-retention#deletion-operations)).                                                           |

`setup`, `login`, and the daemon commands also record your shell's `HTTPS_PROXY` for the daemon, but never replace a recorded proxy with one that does not answer ([Networks that block the tunnel](https://prized.dev/docs/troubleshooting#networks-that-block-the-tunnel)).

### Completions [#completions]

```bash title="zsh"
prized completion zsh > "${fpath[1]}/_prized"
```

```bash title="bash, as root"
prized completion bash > /etc/bash_completion.d/prized
```

```bash title="fish"
prized completion fish > ~/.config/fish/completions/prized.fish
```

Tab then completes commands, flags, box names wherever a `BOX` goes, sizes on `resize`, regions on `move`, and windows on `auto-pause`.

## Global flags [#global-flags]

| Flag            | What it does                                                                                                                                    |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `--json`        | Exactly one JSON object on stdout. Interactive commands reject it; never inferred from a pipe.                                                  |
| `-y, --yes`     | Assume yes for confirmations.                                                                                                                   |
| `-q, --quiet`   | Suppress non-essential output.                                                                                                                  |
| `-v, --verbose` | Verbose output; repeat for wire detail on stderr.                                                                                               |
| `--timeout`     | Per-request network timeout, default 10s.                                                                                                       |
| `--no-color`    | Disable ANSI color; `NO_COLOR` is honored too.                                                                                                  |
| `--box NAME`    | The box to act on (`PRIZED_BOX`): the default box, or another connected with `prized setup --box` ([Several boxes](https://prized.dev/docs/boxes#several-boxes)). |
| `--config PATH` | The config file to use (`PRIZED_CONFIG`). Overrides `--box`; an escape hatch, not the way to a second box.                                      |

## For agents and scripts [#for-agents-and-scripts]

A failing `--json` command prints:

```json
{
  "ok": false,
  "error": { "code": "CHECK_FAILED", "message": "…", "hint": "…" }
}
```

`error.code` maps 1:1 to the exit code, and both are a stable contract:

| Exit | `error.code`            | Meaning                                                                                                    |
| ---- | ----------------------- | ---------------------------------------------------------------------------------------------------------- |
| 0    |                         | Success.                                                                                                   |
| 1    | `INTERNAL`, `AWS_ERROR` | Internal or unexpected error.                                                                              |
| 2    | `USAGE`                 | A bad flag, an unknown size or region, a window without a unit, `box delete --json` without `-y`.          |
| 3    | `BOX_UNREACHABLE`       | Box unreachable (or Prized itself, from your network), or a `--wait` that ran out its five minutes.        |
| 4    | `DAEMON_UNAVAILABLE`    | Daemon required but unavailable.                                                                           |
| 5    | `CHECK_FAILED`          | A precondition failed; the `hint` says what to do. Unknown boxes, sizes not on your plan, refused changes. |
| 6    | `CONFLICT`              | Already exists or cannot fit: a taken box name, the box count, a balance that cannot run the box, a port.  |
| 7    | `PARTIAL`               | A batch partly failed: some items of a `--all` run or an `agents handoff` succeeded, others did not.       |
| 8    | `AUTH`                  | Not signed in, or the token was rejected or expired; run `prized login`.                                   |
| 9    | `MISSING_DEP`           | A dependency is missing; `prized doctor` usually fixes it.                                                 |
| 10   | `DECLINED`              | You declined a confirmation.                                                                               |
| 130  |                         | Interrupted.                                                                                               |

* **Two exceptions.** `prized ssh` and `prized exec` exit with the remote command's code (ssh's 255 when the box cannot be reached); `prized prompt --jsonl` and `prized events --jsonl` print one object per event.
* **`--json` is opt-in.** `prized box ls | head` still prints the table.
* **The same token drives the [edge API](https://prized.dev/docs/exec#the-edge-api)** and every route on the [API reference](https://prized.dev/docs/api), with no `prized` installed.
* **Sign in without a browser.** `prized login --token dcp_…` takes an API key from the dashboard; in a script use `--token-stdin`, since a command line is visible to other programs. The key keeps its expiry and box limit, and login prints both (`this key expires 2026-12-01, reaches 1 box`); once it expires, every command exits 8 with `this API key has expired`. A key limited to some boxes or to less access cannot register a device key, so [Claude Desktop remote](https://prized.dev/docs/claude-desktop) needs a full-access key. Retire keys under [API keys](https://prized.dev/docs/workspaces#api-keys).
* **A whole lifecycle in a script.** `prized box new ci-$RUN --size Small --ttl 2h --wait --json`, work over `prized ssh ci-$RUN -- make test`, then `prized box delete ci-$RUN -y --json`; the deadline is the safety net if the script dies.

## Files [#files]

| Path                                 | What lives there                                                                                                                                                                                                                                               |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `~/.config/prized/config.toml`       | The default box's config: box name, sync projects, port policy, preferred agents (`[agents]`).                                                                                                                                                                 |
| `~/.config/prized/boxes/<name>.toml` | Every other box's config, same schema, with its agent token beside it (`<name>.token`).                                                                                                                                                                        |
| `~/.config/prized/`                  | API key, SSH identity, per-box certificates, and the proxy recorded from your shell (`proxy.json`, readable only by you).                                                                                                                                      |
| `~/.local/state/prized/current-box`  | The box `current` names.                                                                                                                                                                                                                                       |
| `~/Prized/`                          | The default local twin of synced projects.                                                                                                                                                                                                                     |
| `~/.ssh/config.d/prized`             | The SSH stanza that makes `ssh box-3fa9` work everywhere; prized's own commands read it directly, so they work even when `~/.ssh/config` does not apply its Include line. Each alias is bound to the box it first connected to (`prized box rebind` moves it). |
| `~/Library/Logs/prized/`             | Daemon logs (`~/.local/state/prized/` on Linux).                                                                                                                                                                                                               |

On Windows everything but the sync folder and the SSH stanza lives under `%LOCALAPPDATA%\Prized` (`state\`, `cache\`, `logs\`, `mutagen\`, `boxes\`, `bin\`). An install from before the rename keeps its `doppel` names, paths, and `DOPPEL_*` variables; `PRIZED_*` wins when both are set.

## Windows [#windows]

The CLI runs on Windows 10 1809 or later and Windows 11, x64 and arm64, from PowerShell or Windows Terminal ([install line](https://prized.dev/docs/quickstart#2-install-the-cli)); `prized ssh` uses the OpenSSH client that ships with Windows.

| Topic              | What happens                                                                                                                                                                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The daemon         | A Scheduled Task, `PrizedDaemon` (`PrizedDaemon-<name>` for a box connected with `--box`), started at logon, no administrator needed. `daemon stop` and `daemon restart` end it hard, dropping sessions open through it; `prized daemon logs` reads its log. |
| No ControlMaster   | Windows OpenSSH has no connection sharing, so `prized setup` opens one connection per command, a few seconds slower, and every `prized exec` or `prized ssh -- CMD` opens its own.                                                                           |
| Not on Windows yet | `prized mosh`, `prized mount` and `unmount`, drag-and-drop upload in `prized ssh`, and `prized env` (setup skips the environment step and says so).                                                                                                          |
| Symbolic links     | Not synced: a link inside a synced folder stays on the box; every other file syncs.                                                                                                                                                                          |
| Unsigned binaries  | The executables are not Authenticode-signed; see [Troubleshooting](https://prized.dev/docs/troubleshooting#windows).                                                                                                                                                           |

WSL is Linux to Prized: install with the `curl` line inside the distribution.

## Updates [#updates]

At most once every fifteen minutes, after a command finishes, the CLI installs any newer release with the same signed, checksum-verified download as `prized update`, and the next command prints a one-line note. The daemon restarts onto it once no SSH session runs through it (a live `prized ssh` or external SSH client holds it; sync, mounts, port forwards, and mosh do not); `prized version` shows a pending restart, `prized daemon restart` does it now. With [several boxes](https://prized.dev/docs/boxes#several-boxes), each daemon restarts the next time a command reaches its box.

Turn it off with `auto = false` under `[update]` in the config, or `PRIZED_NO_AUTO_UPDATE` in your environment. Homebrew installs are left to `brew upgrade prized`, and from-source builds never self-replace. A CLI below the API's minimum exits 5 with a `prized update` hint; releases before 0.7.0 never update themselves, and the dashboard names a machine still on one.

## Usage telemetry [#usage-telemetry]

While you are signed in, the CLI records which command ran, its version, OS, duration, and exit code, and sends the counts in occasional batches; it never records arguments, flags, paths, or file contents, and sends nothing while you are signed out. A failed `prized setup` step adds one word from a fixed list naming the failed check (the first failing doctor check, if the run stops at its doctor pass), never the message you saw.

Turn it off either way:

```toml
# in ~/.config/prized/config.toml
[telemetry]
enabled = false
```

```bash
# or per shell
export PRIZED_NO_TELEMETRY=1
```

This covers the CLI only; for the website and dashboard, see [Privacy](https://prized.dev/docs/privacy).