pt — the Platinum CLI

Create and drive Platinum sandboxes, templates, volumes, apps and webhooks from your terminal.

npm i -g @platinum-dev/cli    # provides the `pt` command
pt init                       # authenticate + print next steps (`npx @platinum-dev/cli init` also works)
pt sandbox create -t pt-base  # create a sandbox, wait until it's running

Auth

pt login opens the dashboard so you can create an API key, then stores it in your OS keychain (with a ~/.config/platinum/credentials 0600 fallback where no keychain is available). For CI, set the key in the environment — it always wins and never touches disk:

export PLATINUM_API_KEY=pt_live_...

• pt init — first-run setup: logs you in if needed, then prints what to run next (idempotent).
• pt configure --token pt_live_... — set a key non-interactively (also manages named profiles + defaults).
• pt whoami — show the identity/org for the current credentials.
• pt logout — remove stored credentials.

Keys are scoped — mint least-privilege ones with pt key create --name ci --scope sandboxes:read --expires-in 30.

Profiles & config

Non-secret settings live in ~/.config/platinum/config.toml as named [profile …]s (default region, output). Select one with --profile prod or PLATINUM_PROFILE. Precedence everywhere is flag > env > profile > default.

Output

Human tables by default; machine-readable on demand. Honors NO_COLOR.

pt sandbox list                 # table
pt sandbox list -o json | jq .  # JSON for scripting
pt sandbox get <id> -o yaml     # YAML

Commands

| | | |---|---| | pt sandbox create/list/get/exec/wait/expose/stop/start/rm | sandboxes (create auto-waits for running) | | pt template list/get/rm | VM templates | | pt volume list/get/create/rm | persistent volumes | | pt app list/get/deploy/logs/rm | on-demand apps | | pt key list/create/rm/scopes | API keys | | pt webhook list/create/test/rm | webhooks | | pt api <METHOD> <path> | authenticated passthrough to any endpoint | | pt completion bash\|zsh\|fish | shell completion |

Waiters

The sandbox lifecycle is async, so pt waits for you:

pt sandbox create -t pt-base            # blocks until running
pt sandbox create -t pt-base --no-wait  # return immediately
pt sandbox wait <id> --state running --timeout 180

pt api — the escape hatch

Anything without a dedicated command is one request away — no waiting on the CLI to catch up with the API:

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

Development

bun run dev -- sandbox list   # run from source
bun run build                 # bundle to dist/pt.js (tsup)
bun run build:bin             # standalone binaries (bun --compile)