Run commands and files

Run a command on your box and get its exit code back, leave one running and check on it later, and copy files in either direction, from the CLI or from any script that holds a CLI token. Nothing to install on the box.

Run a command

Terminal

prized exec -- make test

The command runs on the box under sh -c in your home directory; stdout, stderr, and the exit code come straight back, and your local stdin is connected. A suspended box wakes first. A box name before the -- picks a box other than the configured one.

Command	What it does
`prized exec -- npm test`	Run in your home on the default box; the exit code is `npm test`'s.
`prized exec box-a7f3 --cwd app -- npm test`	Run on a named box, in `~/app` (`--cwd` is relative to your home, or absolute).
`prized exec --timeout 10m -- ./build.sh`	Kill the command after 10 minutes (TERM, then KILL 5 s later): exit 124, and stderr ends with a `prized: command timed out after 600s (SIGTERM)` line. No limit by default.
`prized exec --env CI=1 --env NODE_ENV=test -- npm test`	Add environment variables (repeatable, up to 32).
`prized exec --json -- make`	Capture instead of stream: one object with `exitCode`, `signal`, `timedOut`, `stdout`, `stderr`.

The words after -- are joined and handed to sh -c, so quote as for ssh: prized exec -- 'cd app && npm test' runs both halves on the box. The shell is a plain sh, not your login shell; tools that only your .bashrc puts on PATH need prized exec -- bash -lc 'npm test'.
Here --timeout is the command's time limit, not the network timeout the other commands use the flag for.
Exit code: the remote command's, or ssh's 255 when the box was unreachable. With --json, ok says whether the command ran and exitCode what it returned; timedOut is true only when the time limit ended the command, so a command that exits 124 on its own is exitCode: 124, timedOut: false.

Detached processes

Terminal

prized exec --detach -- ./train.sh
# started p_3f9c0a1b2d4e (pid 41213) in /home/ubuntu

--detach starts the command and returns at once with a process id. The process outlives your terminal and the ssh session; its output goes to log files on the box.

Command	What it does
`prized exec --detach -- CMD`	Start `CMD` detached (`--cwd` and `--env` apply) and print its id.
`prized exec --status p_3f9c0a1b2d4e`	Running or exited, the exit code or signal, start and finish times, and the tail of each log.
`prized exec --status p_… --tail 1m`	How much of each log to show: bytes, or `4k`, `1m` (default `16k`, cap `1m`).
`prized exec --kill p_3f9c0a1b2d4e`	Stop it: TERM to its process group, then KILL if it is still there after 5 s.
`prized exec --ps`	Every detached process on the box, running or finished.

--status, --kill and --ps never wake a suspended box (they exit 5 and say so); running a command does.

Everything about a detached process lives in one directory on the box, so ls, tail -f, and your own scripts see what the CLI sees:

File in `~/.prized/processes/<id>/`	Contents
`cmd`, `cwd`	The command line as given, and the absolute directory it ran in.
`pid`	The process id (also its process group id).
`boot_id`	The box's boot id at start. After a reboot (a paused box resumes from one) the pid is not trusted: the process reads as `lost` and is never signalled.
`started_at`	Start time, RFC 3339 UTC.
`stdout.log`, `stderr.log`	The output, appended as it happens.
`exit`	Written when the command ends: the exit code, or 128 + signal.

Log directories are never deleted for you. rm -r ~/.prized/processes/p_… on the box when you are done with one.

Copy files

Terminal

prized cp ./notes.md :notes.md

prized cp works like scp: exactly one side is on the box, written BOX:PATH, and a bare :PATH means the configured box. Paths on the box are relative to your home there unless absolute. Files are written whole (a temp file, then a rename), so an interrupted copy never leaves a half-written target; modes are preserved, and symlinks are skipped and counted, a symlink named as SRC included: name the file it points at instead. A hard link (a second name for a file that may live outside the tree, which pnpm and Nix trees are made of) is skipped and counted the same way, and refused when named as SRC; copy it to a new name to send it. A download writes only under DST: an entry that would land outside it stops the copy, and so does a target directory that is itself a symlink; name the directory it points at.

Command	What it does
`prized cp ./file.txt :`	Copy a file into your home on the box, keeping its name.
`prized cp -r ./site box-a7f3:www`	Copy a directory tree (`-r` is required for directories).
`prized cp box-a7f3:logs/app.log ./`	Copy a file from the box into the current directory.
`prized cp -r :proj/dist ./dist`	Copy a directory tree from the box.

For a live view of the whole box in Finder rather than copies, see Mount.

The edge API

Everything above is also HTTP, for scripts and agents that hold a CLI token and have no prized installed. The token comes from Dashboard → Workspace → CLI tokens; the base URL is edge.url in GET /api/v1/me, and every route sits under $EDGE/v1/box/{box}/ (the box's name or id) with the token as the bearer.

Terminal

export PRIZED_TOKEN=dcp_…
EDGE=$(curl -s -H "Authorization: Bearer $PRIZED_TOKEN" https://api.prized.dev/api/v1/me | jq -r .edge.url)

Paths are read the way prized cp reads them, and every answer echoes the real path it touched. Only POST /exec wakes a suspended box; the other routes answer box_not_running. The routes for commands, detached processes, and files are on API reference: The edge; the box's coding agent has its own, described on Prompt an agent remotely.

Errors

A failed request answers {"ok": false, "error": {"code", "message"}}. Every code and what it means is on API reference: Errors.

Limits

Every cap for runs, files, and the edge API, the request rate included, is on Limits.

Run commands and files.

Run a command

Detached processes

Copy files

The edge API

Errors

Limits

On this page