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. With no box, it points at prized box new, then prized setup in a project folder. Signing in this way, through the browser, also gives a new workspace's owner the free credit; signing in with --token does not. 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).

With no box, login also names prized sandbox create: a sandbox needs no box.

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 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, a window out of bounds, or infinite storage the box cannot have.

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.

Terminal dashboard

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:

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.

Sandboxes

prized sandbox (alias prized sbx) runs Sandboxes (beta) from the terminal: short-lived machines your code and agents create, billed per second. It needs prized v0.21.0 or later (prized update upgrades an older one). On a new machine, install it, then open a new terminal so prized is on your PATH (Windows: install line):

curl -fsSL https://prized.dev/install.sh | sh

Every command uses the API key in PRIZED_API_KEY when it is set, so CI and agents need no login, and your prized login otherwise. Get a key from the Sandboxes quickstart.

ID=$(prized sandbox create --template prized-agent-v1)
prized sandbox exec $ID -- "python3 -c 'print(6 * 7)'"
prized sandbox rm $ID

create, get, pause, and resume print {"ok": true, "sandbox": {...}}:

{
  "id": "sbx_3f9c0a1b2d4e5f60", "state": "running", "template": "prized-base-v1",
  "resources": {"vcpu": 2, "memoryMb": 4096, "diskGb": 10},
  "labels": {"job": "ci-42"}, "autoPauseMin": 10, "autoDeleteMin": null,
  "expiresAt": "2026-10-14T10:00:00Z", "createdAt": "2026-10-13T10:00:00Z", "lastActiveAt": null,
  "errorReason": null, "toolboxBase": "https://term.prized.dev/v1/sandbox/sbx_3f9c0a1b2d4e5f60"
}

state is one of starting, running, pausing, paused, resizing, deleting, deleted, error. Exit 6 (CONFLICT): a sandbox limit or an empty balance; on free credit a limit is the free tier's, and the message says so and links the top-up that raises it. Exit 5: a workspace without sandboxes, an unknown template or id, a shape outside the template's range, a workspace on hold, or a refused fork. Exit 8 (AUTH): no login and no PRIZED_API_KEY, or the key was rejected or has expired. A set PRIZED_API_KEY is used instead of your login, so when it is the one rejected, replace it or unset PRIZED_API_KEY; prized login alone does not help.

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

See Agents.

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.

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:

• Three 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; prized box ls --names prints a bare JSON array of names.
• --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. 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 needs a full-access key. 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 --missing-ok (exit 0 if an earlier run already deleted it); 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, or a prized doctor report with a failing check, adds one word from a fixed list naming what failed (for doctor, the first failing check), never the message you saw. CLI use also becomes at most one product event per workspace per UTC day, with the first command's name, the CLI version, and OS; updates and automatic connections do not count (Privacy).

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.