CLI

The @crownest/cli package provides the crownest binary: a command-line interface to sandboxes, commands, files, artifacts, and previews. It's designed for scripting — most commands print JSON — and for quick manual work like tailing logs or killing a sandbox.

Install and run

Install the CLI globally or run it ad hoc with your package manager.

pnpm add -g @crownest/cli
# or
npm install -g @crownest/cli

crownest --help

Log in

Create an API key in the dashboard, then save it to the CLI config file with crownest login.

crownest login --api-key cn_live_... --api-url https://api.crownest.dev

• --api-url defaults to https://api.crownest.dev.
• Without --api-key, login prints guidance instead of saving. You can also set CROWNEST_API_KEY in your environment and run crownest login to save it.

Credentials are written to the config file at ~/.crownest/config.json (or $XDG_CONFIG_HOME/.crownest/config.json when XDG_CONFIG_HOME is set).

Environment variables

The CLI reads these environment variables for credentials, the API endpoint, and the config file location.

Exit codes

The CLI uses three exit codes:

[!IMPORTANT] A sandbox command's own non-zero exit code still exits the CLI with 0 when execution succeeded. The CLI reports the API call's outcome, not your command's. Inspect the exitCode field in the JSON output:

crownest exec sbx_abc123 -- false   # CLI exits 0
# ... "exitCode": 1 ... in the JSON output

Output conventions

Output format depends on the command:

• List and run commands (projects list, sandboxes list, commands run, files list, and so on) print JSON, ready for piping into jq.
• Targeted convenience commands print plain text: sandboxes create prints the new sandbox ID, sandboxes kill prints sbx_... <status>, artifacts create prints the artifact ID, previews create prints the preview URL, and files read writes raw file content to stdout.
• crownest logs streams log output live until the command reaches a terminal state.

Next steps

• Command reference — every command with flags and examples.
• CLI quickstart — a guided first session.
• API keys concept — scopes and key management.