Command reference

Every crownest CLI command with usage, flags, output, and examples, grouped by resource.

This page documents every crownest command. Commands are grouped by the resource they act on. Unless noted otherwise, commands print readable records or tables by default, accept --json for the stable { "data": ... } envelope, and exit 0 on success, 1 on runtime/API error, and 2 on usage errors. Foreground commands run instead returns the sandbox command's exit code, clamped to 125; background runs exit 0 after a successful start. Sandbox exit codes 1 and 2 overlap CLI errors; --json distinguishes command result and error envelopes.

Use crownest help <command> or append --help to a command for command-specific usage. Unknown flags are rejected before any API request.

Quick verbs

These top-level verbs are thin aliases over the canonical resource commands. They use the same API calls, flags, output envelopes, and exit codes.

crownest new

Alias for crownest sandboxes create. Human output includes the shortest next steps; --json remains a pure { "data": ... } envelope.

crownest new [--project <prj_id>] [--template <slug>] [--json]

crownest run

Alias for crownest commands run. Everything after -- is the command that runs inside the Sandbox.

crownest run <sandbox-id> [--background] [--collect <path>]... [--collect-on success|always] [--json] -- <command>

crownest ls

Alias for crownest sandboxes list.

crownest ls [--limit <n>] [--cursor <cursor>] [--all] [--json]

crownest kill

Alias for crownest sandboxes kill.

crownest kill <sandbox-id> [--json]

Authentication

Save credentials to the config file.

crownest login [--api-key <key>] [--api-url <url>] [--json]

Flag	Description
`--api-key`	API key to save. Falls back to `CROWNEST_API_KEY`.
`--api-url`	API base URL. Defaults to `https://api.crownest.dev`.
`--json`	Print `{ "data": ... }`.

Without an API key from either source, login prints guidance for creating one in the dashboard.

Terminal

crownest login --api-key cn_live_abc123
# Saved CrowNest credentials for https://api.crownest.dev.
# Install the CrowNest Agent Skill for compatible coding agents with: crownest skills install

crownest usage

Print your current credit balance, compute use, billing period, and quota buckets.

crownest usage [--json]

Use this command when an API error reports credit_exhausted or quota_exceeded.

crownest whoami

Verify the configured credential and print its safe prefix, name, organization, project restrictions, and scopes.

crownest whoami [--json]

Agent tokens and API keys without api_key:read return verified credential information with unavailable metadata, an explicit missingScopes value, and a verification note. Other authorization failures, including a suspended organization, exit 1. The command never prints the complete credential.

crownest keys create

Create an API key from a human dashboard session.

crownest keys create [--name <name>] [--project <prj_id>] [--scope <scope>]... [--api-url <url>] [--json]

Flag	Description
`--name`	API key display name. Defaults to `CLI key`.
`--project`	Restrict the key to one project (`prj_...`).
`--scope`	Scope to grant. Repeatable; defaults to developer scopes.
`--api-url`	API base URL for key management.
`--json`	Print `{ "data": ... }`.

This command is for dashboard-backed automation contexts. It requires CROWNEST_ORG_ID, CROWNEST_USER_ID, and CROWNEST_ROLE=owner|admin. We recommend most users create project-scoped runtime keys in the dashboard.

Terminal

crownest keys create --name "CI key" --project prj_abc123 --scope sandbox:create --scope command:run
# secret: cn_live_...

crownest keys list

List API keys from a human dashboard session.

crownest keys list [--api-url <url>] [--limit <n>] [--cursor <cursor>] [--all] [--json]

Flag	Description
`--api-url`	API base URL for key management.
`--limit`	Page size from 1 to 500.
`--cursor`	Resume from an opaque cursor.
`--all`	Fetch every remaining page.
`--json`	Print `{ "data": ... }`.

This command requires CROWNEST_ORG_ID, CROWNEST_USER_ID, and CROWNEST_ROLE=owner|admin.

Terminal

crownest keys list --json | jq '.data[] | {id, name, prefix, last4}'

Projects

crownest projects list

List the projects your API key can access.

crownest projects list [--limit <n>] [--cursor <cursor>] [--all] [--json]

Terminal

crownest projects list --json | jq '.data[].id'

Sandboxes

crownest sandboxes create

Create a sandbox.

crownest sandboxes create [--project <prj_id>] [--template <slug>] [--network-policy <mode>] [--network-hosts <host,...>] [--json]

Flag	Description
`--project`	Project to create the sandbox in (`prj_...`).
`--template`	Template slug. `python-node` is the launch template and default.
`--network-policy`	`unrestricted`, `deny-all`, `allowlist`, or `denylist`.
`--network-hosts`	Comma-separated hosts required by `allowlist` and `denylist`.

Terminal

SANDBOX=$(crownest sandboxes create --template python-node --json | jq -r .data.id)
echo "$SANDBOX"
# sbx_abc123

crownest sandboxes list

List live sandboxes.

crownest sandboxes list [--limit <n>] [--cursor <cursor>] [--all] [--json]

Terminal

crownest sandboxes list --json | jq '.data[] | {id, status, expiresAt}'

List commands accept --limit from 1 to 500, --cursor to resume a page, and --all to fetch every remaining page. JSON output includes hasMore and includes nextCursor when another page exists.

crownest sandboxes get

Print one sandbox by ID.

crownest sandboxes get <sandbox-id> [--json]

crownest sandboxes kill

Destroy a sandbox.

crownest sandboxes kill <sandbox-id> [--json]

Argument	Description
`sandbox-id`	The sandbox to destroy (`sbx_...`).

Terminal

crownest sandboxes kill sbx_abc123
# id: sbx_abc123
# status: killed

crownest sandboxes set-ttl

Reset the sandbox TTL countdown from now.

crownest sandboxes set-ttl <sandbox-id> --ttl-ms <ms> [--json]

Flag	Description
`--ttl-ms`	New live sandbox lifetime in milliseconds.

Commands

Everything after -- is the command line executed inside the sandbox.

crownest commands run

Run a command in the foreground by default, or start it in the background. Both modes print the resulting command record.

crownest commands run <sandbox-id> [--background] [--collect <path>]... [--collect-on success|always] [--json] -- <command>

Flag	Description
`--background`	Return immediately after starting the command.
`--collect`	Workspace path to export as an artifact when the command finishes. Repeatable.
`--collect-on`	When to collect: `success` (default) or `always`.

Terminal

crownest commands run sbx_abc123 -- python3 -c 'print(40 + 2)'
# id: cmd_...
# status: exited
# stdout: 42

Foreground runs return the sandbox command's exit code, clamped to 125. Exit codes 1 and 2 overlap CLI API and usage failures, so use --json when automation must distinguish a command result from a CLI error. Background runs exit 0 after the server starts the command successfully.

CMD=$(crownest commands run sbx_abc123 --background --json -- python3 server.py | jq -r .data.id)

--background can't be combined with --collect or --collect-on.

crownest commands get

Print one command, including status, exit code, and captured standard output and standard error.

crownest commands get <command-id> [--json]

crownest commands cancel

Cancel a running command. Prints the updated command record.

crownest commands cancel <command-id> [--force] [--json]

Flag	Description
`--force`	Send `SIGKILL` instead of the default graceful `SIGTERM`.

Terminal

crownest commands cancel cmd_abc123 --force

Workspace Runs

Workspace Runs execute an existing .tar.gz or .tgz archive in a curated CrowNest template and keep a durable Evidence Bundle.

crownest workspace-runs create

Create a Workspace Run record.

crownest workspace-runs create --command <command> [--project <prj_id>] [--template <slug>] [--sandbox <sbx_id>] [--keep-sandbox] [--timeout-ms <ms>] [--metadata key=value]... [--json]

crownest workspace-runs upload

Upload an existing gzipped tar archive to a Workspace Run.

crownest workspace-runs upload <workspace-run-id> <archive.tgz> [--sha256 <hex>] [--json]

crownest workspace-runs start

Start extraction and command execution for an uploaded Workspace Run.

crownest workspace-runs start <workspace-run-id> [--json]

crownest workspace-runs run-archive

Create a run, upload an existing archive, start it, stream output, and exit with the remote command's exit code.

crownest workspace-runs run-archive <archive.tgz> [--project <prj_id>] [--template <slug>] [--sandbox <sbx_id>] [--keep-sandbox] [--timeout-ms <ms>] [--metadata key=value]... [--json] -- <command>

Terminal

crownest workspace-runs run-archive repo.tgz --template python-node -- pnpm test

crownest workspace-runs status

Retrieve Workspace Run status.

crownest workspace-runs status <workspace-run-id> [--json]

crownest workspace-runs list

List Workspace Runs.

crownest workspace-runs list [--project <prj_id>] [--status <status>] [--limit <n>] [--cursor <cursor>] [--all] [--json]

crownest workspace-runs logs

Stream Workspace Run events.

crownest workspace-runs logs <workspace-run-id> [--after-seq <n>] [--json]

crownest workspace-runs cancel

Cancel an active Workspace Run.

crownest workspace-runs cancel <workspace-run-id> [--json]

crownest workspace-runs evidence

Read durable Workspace Run evidence, optionally writing it to a local file.

crownest workspace-runs evidence <workspace-run-id> [--output <path>] [--json]

See CLI Workspace Runs for the full archive-run flow.

Workspace Run Matrices

crownest workspace-run-matrices run

crownest workspace-run-matrices run --archive <workspace.tar.gz> --spec <matrix.json> [--max-concurrency <n>] [--wait] [--json]

crownest workspace-run-matrices get

crownest workspace-run-matrices get <matrix-id> [--json]

crownest workspace-run-matrices list

crownest workspace-run-matrices list [--limit <n>] [--cursor <cursor>] [--all] [--json]

crownest workspace-run-matrices events

crownest workspace-run-matrices events <matrix-id> [--json]

crownest workspace-run-matrices cancel

crownest workspace-run-matrices cancel <matrix-id> [--json]

crownest workspace-run-matrices evidence

crownest workspace-run-matrices evidence <matrix-id> [--json]

Logs

crownest logs

Stream a command's logs live to the terminal until the command reaches a terminal state. Accepts either a command ID directly or a sandbox ID with --command.

crownest logs <command-id> [--json]
crownest logs <sandbox-id> --command <command-id> [--json]

Flag	Description
`--command`	Command ID, when the first argument is a sandbox ID.
`--json`	Accepted for consistency; log stream output stays raw.

Terminal

crownest logs cmd_abc123

Shell

crownest shell

Open a line-oriented sandbox shell. By default, shell creates one Code Context and sends each non-empty line through code run, so variables persist between prompts. Use Ctrl-D, exit, or quit to end the session.

crownest shell <sandbox-id> [--lang python|javascript|typescript] [--bash]

Flag	Description
`--lang`	Code shell language: `python`, `javascript`, or `typescript`.
`--bash`	Run each line as an independent shell command with a `$` prompt.

Terminal

crownest shell sbx_abc123 --lang python
# crownest shell - python - sbx_abc123 - variables persist - Ctrl-D to exit
# >>> x = 41
# >>> print(x + 1)
# 42

--bash runs quick inspection commands. It's not a PTY: each line runs as a separate command, so cd, exported variables, and shell-local state don't carry to the next prompt.

Terminal

crownest shell sbx_abc123 --bash
# crownest shell - bash - sbx_abc123 - each line runs independently; cwd, env, and shell vars do not persist - Ctrl-D to exit
# $ pwd
# /workspace

Agent Skills

crownest skills install

Install the bundled CrowNest Agent Skill into a compatible agent's .agents/skills directory.

crownest skills install [--scope user|project] [--force] [--dry-run] [--json]

Flag	Description
`--scope`	Install location: `user` or `project`. Defaults to user.
`--force`	Replace an existing installed skill.
`--dry-run`	Print the destination without writing.
`--json`	Print `{ "data": ... }`.

Terminal

crownest skills install
# skill: crownest
# scope: user
# installed: true

Code Runs

crownest code run

Run interpreter code in a sandbox. code run streams stdout, stderr, and notebook-style outputs as they arrive, so --json is accepted for flag consistency but does not buffer the stream into a JSON envelope.

crownest code run <sandbox-id> (--code <source> | --file <path>) [--language python|javascript|typescript] [--artifact-policy inline_only|promote] [--timeout-ms <ms>] [--context <cctx_id>] [--cwd <path>] [--idempotency-key <key>] [--json]

Flag	Description
`--code`	Inline source code to run.
`--file`	Local source file to run.
`--language`	Language: `python`, `javascript`, or `typescript`.
`--artifact-policy`	Artifact handling: `inline_only` or `promote`.
`--timeout-ms`	Execution timeout in milliseconds.
`--context`	Existing Code Context ID (`cctx_...`).
`--cwd`	Working directory inside the sandbox.
`--idempotency-key`	Idempotency key for retry-safe requests.
`--json`	Accepted for consistency; streamed output stays raw.

Terminal

crownest code run sbx_abc123 --code 'print(40 + 2)' --language python
# 42

Files

All paths are inside the sandbox workspace, /workspace.

crownest files read

Print a file's raw content to stdout.

crownest files read <sandbox-id> <path> [--json]

Terminal

crownest files read sbx_abc123 results.json | jq .

crownest files write

Write content to a file.

crownest files write <sandbox-id> <path> (<content> | - | --file <local-path>) [--create-parents] [--json]

Flag	Description
`--file`	Read content from a local text file.
`--create-parents`	Create missing parent directories.

Terminal

crownest files write sbx_abc123 notes.txt "hello from crownest"
printf 'one\ntwo\n' | crownest files write sbx_abc123 notes.txt -

crownest files upload

Upload a local file into the sandbox workspace.

crownest files upload <sandbox-id> <local-path> [<remote-path>] [--to <remote-path>] [--create-parents] [--json]

Flag	Description
`--to`	Destination path in the workspace. Defaults to the local file name.
`--create-parents`	Create missing parent directories.

Terminal

crownest files upload sbx_abc123 ./data.csv --to data/input.csv --create-parents

crownest files download

Download a workspace file without converting its bytes to text. The local path defaults to the remote file's base name.

crownest files download <sandbox-id> <remote-path> [<local-path> | --output <path>] [--json]

Providing both a positional local path and --output is a usage error.

crownest files list

List directory entries. Defaults to /workspace.

crownest files list <sandbox-id> [<path>] [--json]

Terminal

crownest files list sbx_abc123 data

crownest files stat

Print metadata for a file or directory.

crownest files stat <sandbox-id> <path> [--json]

Terminal

crownest files stat sbx_abc123 results.json

crownest files mkdir

Create a directory.

crownest files mkdir <sandbox-id> <path> [--parents] [--json]

Flag	Description
`--parents`	Create missing intermediate directories.

Terminal

crownest files mkdir sbx_abc123 data/raw --parents

crownest files move

Move or rename a file or directory.

crownest files move <sandbox-id> <from> <to> [--overwrite] [--json]

Flag	Description
`--overwrite`	Replace an existing destination.

Terminal

crownest files move sbx_abc123 draft.md final.md

crownest files delete

Delete a file or empty directory. There's no recursive delete.

crownest files delete <sandbox-id> <path> [--json]

Terminal

crownest files delete sbx_abc123 tmp/scratch.txt

Artifacts

crownest artifacts create

Export a workspace file as a durable artifact.

crownest artifacts create <sandbox-id> <path> [--name <name>] [--json]

Flag	Description
`--name`	Display name for the artifact. Derived from the path when omitted.

Terminal

crownest artifacts create sbx_abc123 dist/report.pdf --name quarterly-report
# id: art_abc123
# name: quarterly-report

crownest artifacts list

List artifacts exported from a sandbox.

crownest artifacts list <sandbox-id> [--limit <n>] [--cursor <cursor>] [--all] [--json]

crownest artifacts download

Download an artifact to a local file.

crownest artifacts download <artifact-id> --output <path> [--json]

Flag	Description
`--output`	Local path to write the artifact to. Required.

Terminal

crownest artifacts download art_abc123 --output report.pdf

crownest artifacts delete

Delete an artifact from storage.

crownest artifacts delete <artifact-id> [--json]

Terminal

crownest artifacts delete art_abc123

Templates

Template discovery is read-only and requires sandbox:read. Catalogue entries describe the exact curated version that CrowNest has smoke-tested; create a Sandbox or Workspace Run with the returned slug.

crownest templates list

List the curated Template catalogue and its runtime summary.

crownest templates list [--json]

crownest templates get

Inspect one Template's capabilities, languages, package managers, and version.

crownest templates get <template-slug> [--json]

Terminal

crownest templates get node
# slug: node
# status: available
# defaultRuntime: Node.js 22

Previews

crownest previews create

Expose a sandbox port as an authenticated preview. The default output prints the preview URL and, for token-mode previews, the one-time token.

crownest previews create <sandbox-id> --port <port> [--auth-mode authenticated|token] [--json]

Flag	Description
`--port`	Port the service listens on inside the sandbox (1–65535). Required.
`--auth-mode`	Preview auth mode: `authenticated` (default) or `token`. Alias: `--auth`.

Terminal

crownest previews create sbx_abc123 --port 8000
# https://p-a1b2c3.crownest.dev

crownest previews list

List previews for a sandbox.

crownest previews list <sandbox-id> [--limit <n>] [--cursor <cursor>] [--all] [--json]

crownest previews revoke

Revoke a preview so its URL stops serving traffic.

crownest previews revoke <preview-id> [--json]

Terminal

crownest previews revoke prv_abc123

Next steps

CLI overview — login, config, env vars, and exit codes.
CLI quickstart — a guided first session.
API error reference — error codes printed on failures.

On this page