CLI
Install the crownest CLI, log in, configure credentials, and understand exit codes and output formats.
The @crownest/cli package provides the crownest binary: a command-line
interface to sandboxes, commands, Workspace Runs, files, artifacts, and
previews. Use --json for scripting, or the readable default output 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 --helpRun crownest help <command> for command-specific usage.
crownest help sandboxes createInstall the bundled CrowNest Agent Skill when you want compatible coding agents to discover CrowNest workflows automatically.
crownest skills installLog 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-urldefaults tohttps://api.crownest.dev.- Without
--api-key,loginprints guidance instead of saving. You can also setCROWNEST_API_KEYin your environment and runcrownest loginto save it.
Credentials are written to the config file at
~/.config/crownest/config.json (or $XDG_CONFIG_HOME/crownest/config.json
when XDG_CONFIG_HOME is set), with mode 0600. Override the location with
CROWNEST_CONFIG_PATH.
Run code
Create a Sandbox and run code without learning the resource namespaces first.
crownest new
crownest run <sandboxId> -- python3 -c "print('hello from crownest')"crownest new --json is available when a script needs to capture the generated
Sandbox ID. The full resource-shaped commands remain available in the command
reference.
Environment variables
The CLI reads these environment variables for credentials, the API endpoint, and the config file location.
| Variable | Default | Description |
|---|---|---|
CROWNEST_BEARER_TOKEN | — | Preferred credential. Accepts cn_agent_… agent tokens or cn_live_… keys. |
CROWNEST_API_KEY | — | API key used when no bearer token or saved credentials apply. |
CROWNEST_API_URL | https://api.crownest.dev | API base URL. |
CROWNEST_CONFIG_PATH | ~/.config/crownest/config.json | Config file location (overrides the default path). |
Exit codes
The CLI uses three exit codes:
| Exit code | Meaning |
|---|---|
0 | Success. |
1 | Error — details are printed to stderr. |
2 | Usage error — wrong arguments or flags. |
Unknown commands and unknown flags are usage errors. A misspelled flag is rejected before any API request is made.
crownest sandboxes create --templte python-node
# unknown flag: --templte (valid: --project, --template, --json)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 commands run sbx_abc123 -- false # CLI exits 0
# ... "exitCode": 1 ... in the JSON outputOutput conventions
The default output is optimized for humans. Use --json when scripting.
- Resource commands print aligned
key: valuerecords or tabular lists. --jsonprints a compact, stable envelope:{ "data": ... }.crownest logsstreams log output live until the command reaches a terminal state.crownest code runstreams code stdout, stderr, and notebook-style outputs as they arrive.crownest workspace-runs run-archiveruns an existing.tar.gzor.tgzarchive remotely and exits with the remote command's exit code.crownest files readwrites raw file content to stdout unless--jsonis present.
crownest sandboxes create --template python-node
# id: sbx_abc123
# status: ready
# expiresAt: 2026-06-09T15:30:00.000Z
crownest sandboxes create --template python-node --json | jq -r .data.id
# sbx_abc123Next steps
- Command reference — every command with flags and examples.
- Workspace Runs — run an existing archive and keep durable evidence.
- CLI quickstart — a guided first session.
- API keys concept — scopes and key management.