# Command reference (/docs/cli/commands)



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 [#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 [#crownest-new]

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

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

### crownest run [#crownest-run]

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

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

### crownest ls [#crownest-ls]

Alias for `crownest sandboxes list`.

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

### crownest kill [#crownest-kill]

Alias for `crownest sandboxes kill`.

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

## Authentication [#authentication]

### crownest login [#crownest-login]

Save credentials to the config file.

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

```bash title="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 [#crownest-usage]

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

```bash
crownest usage [--json]
```

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

### crownest whoami [#crownest-whoami]

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

```bash
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 [#crownest-keys-create]

Create an API key from a human dashboard session.

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

```bash title="Terminal"
crownest keys create --name "CI key" --project prj_abc123 --scope sandbox:create --scope command:run
# secret: cn_live_...
```

### crownest keys list [#crownest-keys-list]

List API keys from a human dashboard session.

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

```bash title="Terminal"
crownest keys list --json | jq '.data[] | {id, name, prefix, last4}'
```

## Projects [#projects]

### crownest projects list [#crownest-projects-list]

List the projects your API key can access.

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

```bash title="Terminal"
crownest projects list --json | jq '.data[].id'
```

## Sandboxes [#sandboxes]

### crownest sandboxes create [#crownest-sandboxes-create]

Create a sandbox.

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

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

### crownest sandboxes list [#crownest-sandboxes-list]

List live sandboxes.

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

```bash title="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 [#crownest-sandboxes-get]

Print one sandbox by ID.

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

### crownest sandboxes kill [#crownest-sandboxes-kill]

Destroy a sandbox.

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

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

```bash title="Terminal"
crownest sandboxes kill sbx_abc123
# id: sbx_abc123
# status: killed
```

### crownest sandboxes set-ttl [#crownest-sandboxes-set-ttl]

Reset the sandbox TTL countdown from now.

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

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

## Commands [#commands]

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

### crownest commands run [#crownest-commands-run]

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

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

```bash title="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.

```bash
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 [#crownest-commands-get]

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

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

### crownest commands cancel [#crownest-commands-cancel]

Cancel a running command. Prints the updated command record.

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

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

```bash title="Terminal"
crownest commands cancel cmd_abc123 --force
```

## Workspace Runs [#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 [#crownest-workspace-runs-create]

Create a Workspace Run record.

```bash
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 [#crownest-workspace-runs-upload]

Upload an existing gzipped tar archive to a Workspace Run.

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

### crownest workspace-runs start [#crownest-workspace-runs-start]

Start extraction and command execution for an uploaded Workspace Run.

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

### crownest workspace-runs run-archive [#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.

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

```bash title="Terminal"
crownest workspace-runs run-archive repo.tgz --template python-node -- pnpm test
```

### crownest workspace-runs status [#crownest-workspace-runs-status]

Retrieve Workspace Run status.

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

### crownest workspace-runs list [#crownest-workspace-runs-list]

List Workspace Runs.

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

### crownest workspace-runs logs [#crownest-workspace-runs-logs]

Stream Workspace Run events.

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

### crownest workspace-runs cancel [#crownest-workspace-runs-cancel]

Cancel an active Workspace Run.

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

### crownest workspace-runs evidence [#crownest-workspace-runs-evidence]

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

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

See [CLI Workspace Runs](/docs/cli/workspace-runs) for the full
archive-run flow.

## Workspace Run Matrices [#workspace-run-matrices]

### crownest workspace-run-matrices run [#crownest-workspace-run-matrices-run]

```bash
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]

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

### crownest workspace-run-matrices list [#crownest-workspace-run-matrices-list]

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

### crownest workspace-run-matrices events [#crownest-workspace-run-matrices-events]

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

### crownest workspace-run-matrices cancel [#crownest-workspace-run-matrices-cancel]

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

### crownest workspace-run-matrices evidence [#crownest-workspace-run-matrices-evidence]

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

## Logs [#logs]

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

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

```bash title="Terminal"
crownest logs cmd_abc123
```

## Shell [#shell]

### crownest 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.

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

```bash title="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.

```bash title="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 [#agent-skills]

### crownest skills install [#crownest-skills-install]

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

```bash
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": ... }`.                                 |

```bash title="Terminal"
crownest skills install
# skill: crownest
# scope: user
# installed: true
```

## Code Runs [#code-runs]

### crownest code run [#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.

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

```bash title="Terminal"
crownest code run sbx_abc123 --code 'print(40 + 2)' --language python
# 42
```

## Files [#files]

All paths are inside the sandbox workspace, `/workspace`.

### crownest files read [#crownest-files-read]

Print a file's raw content to stdout.

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

```bash title="Terminal"
crownest files read sbx_abc123 results.json | jq .
```

### crownest files write [#crownest-files-write]

Write content to a file.

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

```bash title="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 [#crownest-files-upload]

Upload a local file into the sandbox workspace.

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

```bash title="Terminal"
crownest files upload sbx_abc123 ./data.csv --to data/input.csv --create-parents
```

### crownest files download [#crownest-files-download]

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

```bash
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 [#crownest-files-list]

List directory entries. Defaults to `/workspace`.

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

```bash title="Terminal"
crownest files list sbx_abc123 data
```

### crownest files stat [#crownest-files-stat]

Print metadata for a file or directory.

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

```bash title="Terminal"
crownest files stat sbx_abc123 results.json
```

### crownest files mkdir [#crownest-files-mkdir]

Create a directory.

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

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

```bash title="Terminal"
crownest files mkdir sbx_abc123 data/raw --parents
```

### crownest files move [#crownest-files-move]

Move or rename a file or directory.

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

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

```bash title="Terminal"
crownest files move sbx_abc123 draft.md final.md
```

### crownest files delete [#crownest-files-delete]

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

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

```bash title="Terminal"
crownest files delete sbx_abc123 tmp/scratch.txt
```

## Artifacts [#artifacts]

### crownest artifacts create [#crownest-artifacts-create]

Export a workspace file as a durable artifact.

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

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

```bash title="Terminal"
crownest artifacts create sbx_abc123 dist/report.pdf --name quarterly-report
# id: art_abc123
# name: quarterly-report
```

### crownest artifacts list [#crownest-artifacts-list]

List artifacts exported from a sandbox.

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

### crownest artifacts download [#crownest-artifacts-download]

Download an artifact to a local file.

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

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

```bash title="Terminal"
crownest artifacts download art_abc123 --output report.pdf
```

### crownest artifacts delete [#crownest-artifacts-delete]

Delete an artifact from storage.

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

```bash title="Terminal"
crownest artifacts delete art_abc123
```

## Templates [#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 [#crownest-templates-list]

List the curated Template catalogue and its runtime summary.

```bash
crownest templates list [--json]
```

### crownest templates get [#crownest-templates-get]

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

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

```bash title="Terminal"
crownest templates get node
# slug: node
# status: available
# defaultRuntime: Node.js 22
```

## Previews [#previews]

### crownest previews create [#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.

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

```bash title="Terminal"
crownest previews create sbx_abc123 --port 8000
# https://p-a1b2c3.crownest.dev
```

### crownest previews list [#crownest-previews-list]

List previews for a sandbox.

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

### crownest previews revoke [#crownest-previews-revoke]

Revoke a preview so its URL stops serving traffic.

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

```bash title="Terminal"
crownest previews revoke prv_abc123
```

## Next steps [#next-steps]

* [CLI overview](/docs/cli) — login, config, env vars, and exit codes.
* [CLI quickstart](/docs/quickstart/cli) — a guided first session.
* [API error reference](/docs/api/errors) — error codes printed on
  failures.