# CLI (/docs/cli)



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-and-run]

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

```bash title="Terminal"
pnpm add -g @crownest/cli
# or
npm install -g @crownest/cli

crownest --help
```

Run `crownest help <command>` for command-specific usage.

```bash title="Terminal"
crownest help sandboxes create
```

Install the bundled CrowNest Agent Skill when you want compatible coding
agents to discover CrowNest workflows automatically.

```bash title="Terminal"
crownest skills install
```

## Log in [#log-in]

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

```bash title="Terminal"
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
`~/.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 [#run-code]

Create a Sandbox and run code without learning the resource namespaces first.

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

```bash title="Terminal"
crownest sandboxes create --templte python-node
# unknown flag: --templte (valid: --project, --template, --json)
```

<Callout type="warn" title="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:

  ```bash
  crownest commands run sbx_abc123 -- false   # CLI exits 0
  # ... "exitCode": 1 ... in the JSON output
  ```
</Callout>

## Output conventions [#output-conventions]

The default output is optimized for humans. Use `--json` when scripting.

* Resource commands print aligned `key: value` records or tabular lists.
* `--json` prints a compact, stable envelope: `{ "data": ... }`.
* `crownest logs` streams log output live until the command reaches a
  terminal state.
* `crownest code run` streams code stdout, stderr, and notebook-style
  outputs as they arrive.
* `crownest workspace-runs run-archive` runs an existing `.tar.gz` or
  `.tgz` archive remotely and exits with the remote command's exit code.
* `crownest files read` writes raw file content to stdout unless `--json`
  is present.

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

## Next steps [#next-steps]

* [Command reference](/docs/cli/commands) — every command with flags and
  examples.
* [Workspace Runs](/docs/cli/workspace-runs) — run an existing archive and
  keep durable evidence.
* [CLI quickstart](/docs/quickstart/cli) — a guided first session.
* [API keys concept](/docs/concepts/api-keys) — scopes and key
  management.