CrowNest Docs

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 JSON to stdout and exit 0 on success, 1 on error, and 2 on usage errors — see output conventions.

Authentication

Save credentials to the config file.

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

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`.

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

Terminal

crownest login --api-key cn_live_abc123
# Saved CrowNest credentials for https://api.crownest.dev.

Projects

crownest projects list

List the projects your API key can access. Prints JSON.

crownest projects list

Terminal

crownest projects list | jq '.[].id'

Sandboxes

crownest sandboxes create

Create a sandbox. Prints the new sandbox ID.

crownest sandboxes create [--project <prj_id>] [--template <slug>]

Flag	Description
`--project`	Project to create the sandbox in (`prj_...`).
`--template`	Template slug: `python`, `node`, `python-node`, or `base`.

Terminal

SANDBOX=$(crownest sandboxes create --template python)
echo "$SANDBOX"
# sbx_abc123

crownest sandboxes list

List live sandboxes. Prints JSON.

crownest sandboxes list

Terminal

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

crownest sandboxes kill

Destroy a sandbox. Prints the sandbox ID and its resulting status.

crownest sandboxes kill <sandbox-id>

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

Terminal

crownest sandboxes kill sbx_abc123
# sbx_abc123 destroyed

Commands

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

crownest exec

Run a command and wait for it to exit. Alias of crownest commands run. Prints the resulting command record as JSON.

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

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

Terminal

crownest exec sbx_abc123 -- python -c 'print(40 + 2)'
# { "id": "cmd_...", "status": "exited", "exitCode": 0, "stdout": "42\n", ... }

[!NOTE] The CLI exits 0 even when the executed command's exitCode is non-zero, as long as execution succeeded. Check the JSON.

crownest commands run

Identical to crownest exec.

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

Terminal

crownest commands run sbx_abc123 --collect report.xml --collect-on always -- pytest -q

crownest commands start

Start a command without waiting. Prints the command record as JSON with status queued or starting. start doesn't support --collect.

crownest commands start <sandbox-id> -- <command>

Terminal

CMD=$(crownest commands start sbx_abc123 -- python server.py | jq -r .id)

crownest commands cancel

Cancel a running command. Prints the updated command record as JSON.

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

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

Terminal

crownest commands cancel cmd_abc123 --force

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>
crownest logs <sandbox-id> --command <command-id>

Flag	Description
`--command`	Command ID, when the first argument is a sandbox ID.

Terminal

crownest logs cmd_abc123

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>

Terminal

crownest files read sbx_abc123 results.json | jq .

crownest files write

Write content to a file.

crownest files write <sandbox-id> <path> <content> [--create-parents]

Flag	Description
`--create-parents`	Create missing parent directories.

Terminal

crownest files write sbx_abc123 notes.txt "hello from crownest"

crownest files upload

Upload a local file into the sandbox workspace.

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

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 list

List directory entries. Defaults to /workspace. Prints JSON.

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

Terminal

crownest files list sbx_abc123 data

crownest files stat

Print metadata for a file or directory as JSON.

crownest files stat <sandbox-id> <path>

Terminal

crownest files stat sbx_abc123 results.json

crownest files mkdir

Create a directory.

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

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]

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>

Terminal

crownest files delete sbx_abc123 tmp/scratch.txt

Artifacts

crownest artifacts create

Export a workspace file as a durable artifact. Prints the artifact ID.

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

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
# art_abc123

crownest artifacts list

List artifacts exported from a sandbox. Prints JSON.

crownest artifacts list <sandbox-id>

crownest artifacts download

Download an artifact to a local file.

crownest artifacts download <artifact-id> --output <path>

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

Terminal

crownest artifacts download art_abc123 -o report.pdf

crownest artifacts delete

Delete an artifact from storage.

crownest artifacts delete <artifact-id>

Terminal

crownest artifacts delete art_abc123

Previews

crownest previews create

Expose a sandbox port as an authenticated preview. Prints the preview URL.

crownest previews create <sandbox-id> --port <port>

Flag	Description
`--port`	Port the service listens on inside the sandbox (1–65535). Required.

Terminal

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

crownest previews list

List previews for a sandbox. Prints JSON.

crownest previews list <sandbox-id>

crownest previews revoke

Revoke a preview so its URL stops serving traffic.

crownest previews revoke <preview-id>

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.

Command reference

Authentication

Projects

crownest projects list

Sandboxes

crownest sandboxes create

crownest sandboxes list

crownest sandboxes kill

Commands

crownest exec

crownest commands run

crownest commands start

crownest commands cancel

Logs

crownest logs

Files

crownest files read

crownest files write

crownest files upload

crownest files list

crownest files stat

crownest files mkdir

crownest files move

crownest files delete

Artifacts

crownest artifacts create

crownest artifacts list

crownest artifacts download

crownest artifacts delete

Previews

crownest previews create

crownest previews list

crownest previews revoke

Next steps

On this page