CLI

The pt command. Manage sandboxes, templates, volumes, apps, and webhooks from your terminal.

The Platinum CLI is the pt command. It creates sandboxes, builds templates, and manages volumes, apps, and webhooks. Use it for interactive work, scripts, and CI.

npm install -g @platinum-dev/cli
pt init
pt sandbox create -t pt-base

Authenticate

pt login mints an API key in your browser and passes it to the CLI. The CLI stores the API key in your OS keychain. Without a keychain, it uses ~/.config/platinum/credentials.

Command	What it does
`pt init`	First-run setup. Logs in if needed and prints next steps. Idempotent.
`pt login`	Browser flow: approve in the dashboard, and the key returns to the CLI. `--no-browser` pastes a key instead. `--token pt_live_…` skips the browser.
`pt logout`	Remove stored credentials for the current profile.
`pt configure --token pt_live_… [--region r]`	Set an API key and defaults without prompts. Verifies the key before it saves.
`pt whoami`	Show user, org, role, key source, and enabled features.

In CI, set the API key in the environment. The environment wins over stored credentials and never touches disk.

export PLATINUM_API_KEY=pt_live_…

Mint scoped API keys for automation: pt key create --name ci --scope sandboxes:read --expires-in 30. See API keys.

Global flags and environment variables

Every command accepts these flags, before or after the subcommand.

Flag	Meaning
`-o, --output table\|json\|yaml`	Output format (default `table`).
`-q, --quiet`	Minimal output — `pt sandbox create -q` prints only the id.
`--profile <name>`	Named profile to use.
`--api-url <url>`	Override the API base URL.
`--no-input`	Never prompt (CI).
`--debug`	Log HTTP to stderr.

Env var	Meaning
`PLATINUM_API_KEY`	API key. Wins over stored credentials (`PT_TOKEN` also honored).
`PLATINUM_PROFILE`	Profile to use.
`PLATINUM_API_URL`	API base URL (`PT_API_URL` also honored).
`PLATINUM_OUTPUT`	Default output format.
`PLATINUM_REGION`	Default region.
`PLATINUM_WEB_URL`	Dashboard origin for `pt login` and `pt open`.

Precedence everywhere: flag > env > profile > default. Tables honor NO_COLOR.

Switch profiles

Non-secret settings live in ~/.config/platinum/config.toml as named profiles. Each profile carries its own org-scoped API key. Use one profile per org to switch accounts.

Command	What it does
`pt config get`	Resolved settings for the current profile.
`pt config list`	List profiles (default marked).
`pt config use <profile>`	Switch the default profile.
`pt config set <key> <value>`	Set `url` \| `web` \| `region` \| `output` per profile.

pt login --profile staging --api-url https://api.staging.example.com
pt config use staging

Manage sandboxes

See Sandboxes, Exec, Filesystem, Snapshots, and Networking.

Create, inspect, and control

Command	What it does
`pt sandbox create [-t tpl] [--name n] [--cpu N] [--ram MB] [--disk GB] [--region r] [--env K=V,K2=V2] [--no-wait] [--timeout s]`	Create and wait until `running` (default timeout 120 s). No `-t` → auto-picks a ready template in your org (prefers `pt-base`).
`pt sandbox list [--state s] [--limit n]`	List sandboxes (default 50). `ls` works too.
`pt sandbox get <id>`	Show one sandbox.
`pt sandbox rename <id> <name>`	Rename a sandbox. `--clear` removes the name.
`pt sandbox wait <id> [--state s] [--timeout sec]`	Block until a state (default `running`, 120 s). Stops early on failure states.
`pt sandbox metrics <id>`	Live CPU / memory / disk.
`pt sandbox resize <id> [--cpu N] [--ram MB] [--disk GB]`	Resize a stopped sandbox.
`pt sandbox stop\|start\|pause\|resume <id>`	Lifecycle transitions.
`pt sandbox archive <id>`	Archive a stopped sandbox to cold storage. `start` restores it.
`pt sandbox rm <id>`	Delete (`delete` works too).

Run commands and move files

Command	What it does
`pt sandbox exec <id> '<cmd>'`	Run a command and wait (default timeout 30 s). Prints output and exits with the command's exit code. To keep a process alive after `exec` returns, start it with `setsid`.
`pt sandbox run-code <id> '<code>' [--lang python] [--file f]`	Run a code snippet in one call. `lang` is `python` (default), `node`, `bash`, or `sh`. Reads `--file` or stdin when no code arg. Exits with the code's exit code.
`pt sandbox ssh <id>`	Open an interactive shell in the sandbox (`shell` works too). A PTY over the API's auth channel — no port 22, no SSH keys, no network exposure. Ctrl-D or `exit` to leave. Pipe stdin to script it: `echo 'ls -la' \| pt sandbox ssh <id>`.
`pt sandbox cp ./local <id>:/path`	Copy a file in. Copy out with `pt sandbox cp <id>:/path ./local`.
`pt sandbox fs ls\|read\|write\|rm\|mkdir\|stat <id> <path>`	Filesystem operations. `write` reads stdin (or `--from <file>`). `rm -r` recurses.
`pt sandbox fs find <id> <glob> [--path p] [--max n]`	Find files by name glob.
`pt sandbox fs grep <id> <pattern> [--path p] [--max n]`	Search file contents (`file:line:content` per match).
`pt sandbox fs replace <id> <find> <replace> [--path p] [--glob g]`	Regex find/replace across files.
`pt sandbox fs watch <id> [path] [--interval ms] [--max-seconds s]`	Stream file-change events (SSE). Ends after `--max-seconds` (default 300).
`pt sandbox expose <id> <port>`	Expose a port and print its preview URL (signed unless exposed publicly).
`pt sandbox unexpose <id> <port>`	Remove a port exposure. Kills every token minted for it.
`pt sandbox revoke <id> <token> [--reason r]`	Revoke one preview token. The exposure stays up.
`pt sandbox egress <id> --mode allow\|deny [--cidrs c1,c2]`	Set the outbound network policy. `allow` = allowlist, `deny` = denylist.
`pt sandbox egress-clear <id>`	Clear the egress policy — allow all outbound.
`pt sandbox open <id> [port]`	Open a port URL in the browser (exposes it first when a port is given).

Snapshot and clone

Command	What it does
`pt sandbox snapshot <id>`	Point-in-time disk snapshot of a running sandbox.
`pt sandbox snapshots <id>`	List its snapshots.
`pt sandbox snapshot-rm <id> <snap>`	Delete one snapshot.
`pt sandbox restore <id> [--snapshot id] [--no-wait] [--timeout s]`	Roll a sandbox back to a snapshot (latest by default). Waits for `running`.
`pt sandbox fork <id>`	Fork a running sandbox into a new one.
`pt sandbox clone <id> [--snapshot id]`	New sandbox from the latest (or a given) snapshot.
`pt sandbox backup <id>`	Back up a running sandbox's filesystem off-host.
`pt sandbox restore-from-backup <id>`	Cold-boot the sandbox from its latest backup.

Build templates

See Templates.

Command	What it does
`pt template build <name> --image <ref> [--entrypoint cmd]`	Build from an image.
`pt template build <name> --repo <url> [--ref r] [--subdir d] [--dockerfile f] [--token t]`	Build from a git repo's Dockerfile. Requires the apps feature for your org.
`pt template list` / `get <id>`	List / show templates.
`pt template update <id> [--version v] [--cpu N] [--ram MB] [--disk GB] [--entrypoint cmd]`	Update version or sandbox defaults. Rebuild to change the image.
`pt template rm <id>`	Delete.

Build flags: --cpu, --ram, and --disk set the template's sandbox defaults. --size-mb caps the rootfs. --region pins the build. --wait blocks until ready (--timeout, default 1800 s).

Manage volumes

pt volume is feature-gated per org. If the API reports the feature is not enabled, it is not available for your org yet. See Volumes.

Command	What it does
`pt volume create --size <GB> [--mount-path p] [--sandbox id] [--host id]`	Create a volume. Pin to a sandbox (hot-attaches if running) or a host.
`pt volume attach <id> --sandbox <id> [--mount-path p]`	Attach a volume to a running sandbox on the same host.
`pt volume detach <id>`	Detach a volume from its sandbox.
`pt volume list` / `get <id>` / `rm <id>`	List / show / delete.

Deploy apps

pt app is feature-gated per org. Apps deploy an image behind a public URL — on-demand, with releases and rollback.

Command	What it does
`pt app create <slug> --image <ref> --port <n> [--health-path /] [--env K=V,…] [--cpu N] [--ram MB] [--region r]`	Create an app from an image. Git-source apps: `pt api POST /v1/apps`.
`pt app deploy <id>`	Trigger a new deployment.
`pt app deployments <id>`	Release history.
`pt app rollback <id> [--release n]`	Roll back (default: the previous release).
`pt app logs <id>`	Recent logs.
`pt app open <id>`	Open the app URL in the browser.
`pt app start\|stop\|restart <id>`	Lifecycle.
`pt app list` / `get <id>` / `rm <id>`	List / show / delete.

Manage keys and webhooks

See API keys and Webhooks.

Command	What it does
`pt key create --name <n> [--scope a,b] [--expires-in days]`	Mint an API key — the secret prints once. Default scope `*`.
`pt key scopes`	Available scopes + presets.
`pt key list` / `rm <id>`	List / revoke.
`pt webhook create --url https://… [--events a,b]`	Add an endpoint — the signing secret prints once. Default events `*`.
`pt webhook update <id> [--enable\|--disable] [--url u] [--events a,b]`	Pause/resume, or change the url or events.
`pt webhook test <id>`	Send a test event.
`pt webhook deliveries <id> [--status s]`	List delivery attempts. Filter by status (`failed`, `dead_letter`, …).
`pt webhook retry <id> <deliveryId>`	Retry one failed or dead-letter delivery.
`pt webhook list` / `rm <id>`	List / delete.

View billing and audit

See Billing and Audit log. Both read org-scoped data. Limits and the audit log are owner/admin only.

Command	What it does
`pt billing account`	Show the org account — plan, credits, status.
`pt billing usage`	Current billing-period usage.
`pt billing ledger [--limit n]`	Credit ledger entries — top-ups and charges.
`pt billing limits`	Show usage limits.
`pt billing limits [--limit USD] [--alert USD]`	Set the monthly limit or alert threshold. Empty string clears one.
`pt audit list [--action prefix] [--actor id] [--status s] [--limit n]`	List audit-log events (owner/admin only). Filter by action prefix, actor, or status.

Wire up an AI agent

pt mcp runs a stdio MCP server and adds it to your coding agent's config. See AI agents for the tool list and scoping.

Command	What it does
`pt mcp init <claude\|cursor\|windsurf>`	Merge the server into the agent's MCP config (backs up to `.bak`; writes no token).
`pt mcp config [--with-token]`	Print the config snippet. `--with-token` embeds a plaintext key for clients that cannot read the keychain.
`pt mcp start [--readonly] [--permissions <groups>] [--sandbox <id>]`	Run the server on stdio. Agents launch this; you rarely run it by hand.

Call any endpoint

pt api reaches the entire REST API. Anything without a dedicated command is one request away.

pt api /v1/sandboxes
pt api POST /v1/sandboxes -d '{"template":"pt-base","cpu":2}'
pt api /v1/sandboxes/<id>/metrics -o yaml

Command	What it does
`pt api [METHOD] <path> [-d json\|@file\|-] [--query "k=v&k2=v2"]`	Authenticated request to any endpoint. GET by default (POST when `-d` is given).
`pt open`	Open the dashboard.
`pt completion bash\|zsh\|fish`	Shell completion script (top-level commands).
`pt update [--dry-run]`	Update the CLI to the latest version (`upgrade` works too).

Full flags for any command: pt <cmd> --help.

Put it together

Create → run → serve. setsid keeps the server alive after exec returns.

SBX=$(pt sandbox create -t pt-base -q)
pt sandbox cp ./server.sh $SBX:/workspace/server.sh
pt sandbox exec $SBX 'setsid sh /workspace/server.sh >/tmp/server.log 2>&1 </dev/null &'
URL=$(pt sandbox expose $SBX 8080)
curl "$URL"

Custom template → sandbox. Build once, create many.

pt template build py312 --image python:3.12-slim --wait
SBX=$(pt sandbox create -t py312 -q)
pt sandbox exec $SBX 'python3 -V'

Scripting / CI. Scoped API key via env, JSON output into jq.

export PLATINUM_API_KEY=pt_live_…
pt sandbox list --state running -o json | jq -r '.[].id'
pt sandbox exec "$SBX" 'make test' || echo "tests failed with $?"

On this page