CLI reference

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.

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

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); 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"}.

prized start is what npx prized 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).

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).

Box lifecycle

Every action also works from the dashboard; what each does is on 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. Until a plan is live, the 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

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.

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

Each prints {"ok": true, "box": {...}} with the box object unless noted.

The box object

{
  "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.

Snapshots

Behaviour, kinds, and limits: Snapshots.

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.

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).

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

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). Flags: -s, --session NAME (default main), --ls, --kill NAME (asks unless -y), --raw (no tmux), --no-forward, --no-drop-upload, --no-clipboard (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 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

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"}. 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, and both report what they did (never output or contents) to the audit log as a reported row.

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.

Sync

prized sync add PROJECT | add --local PATH mirrors a folder between the box and this machine (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

prized mount [BOX] mounts a box in Finder from a background process and returns, macOS only (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

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

prized ports share PORT prints a prized.dev link sharing the port with your workspace (the same link again for a shared port); prized ports share alone lists the box's shared ports; prized ports unshare PORT stops sharing (Share a port with your team). A bad port exits 2 before any call; a port that is not shared exits 5. JSON: share PORT {"share": {"id", "boxId", "hostname", "port", "slug", "url", "createdBy", "createdAt", "openCount", "lastOpenedAt"}, "created"}; share {"enabled", "shares": [...]}; unshare {"share", "revoked": true}.

Agents

See Agents.

Prompt an agent remotely

prized prompt [BOX] --provider claude|codex [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, --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).

prized prompt ls [BOX] lists runs; prized events [BOX] [--run ID] [--follow] [--after N] shows or follows one; prized interrupt [BOX] [--run ID] stops the run in progress. Only prompt wakes a box. Exit: 0 when the run ends cleanly, 1 when it failed or was interrupted, 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 ls {"runs", "active"}; events {"run", "events", "next", "finished"}; interrupt {"id", "wasRunning", "signal"}. Shapes: Prompt an agent remotely.

Team

prized team status is what the team is doing now, prized team log what happened; neither needs a box config (Teams).

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.

team log prints the 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

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). 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"}]}.

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).

Completions

prized completion zsh > "${fpath[1]}/_prized"

prized completion bash > /etc/bash_completion.d/prized

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

For agents and scripts

A failing --json command prints:

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

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

• 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 and every route on the API reference, 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. Retire keys under 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

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

The CLI runs on Windows 10 1809 or later and Windows 11, x64 and arm64, from PowerShell or Windows Terminal (install line); prized ssh uses the OpenSSH client that ships with Windows.

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

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, 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

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:

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

# or per shell
export PRIZED_NO_TELEMETRY=1

This covers the CLI only; for the website and dashboard, see Privacy.