# CLI

Reference for the `nanocode` binary and its `nc` alias: every subcommand, option, and environment variable.

The binary comes from the `nanocode-cli` package. [Terminal UI](/docs/guides/cli) covers installation and sign-in, and [Headless Runs](/docs/guides/exec) covers scripts and CI.

```bash
# Open the interface with a first prompt
nc "fix the failing test"
```

## Signature

```bash
# Open the interface, or run a subcommand
nc [OPTIONS] [PROMPT]
nc <exec|resume|sessions|models|hand> [ARGS]
```

Without a subcommand, `nc` opens the interactive interface in the workspace. The interface needs a terminal on stdin and stdout.

## Commands

| Command            | Behavior                                                                                                                    |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `nc [PROMPT]`      | Opens the interface, then sends `PROMPT` when the session is ready                                                          |
| `nc exec <PROMPT>` | Runs one prompt without the interface. The reply streams to stdout, and reasoning summaries and tool calls stream to stderr |
| `nc resume [ID]`   | Resumes a saved session, or opens a picker without an ID                                                                    |
| `nc sessions [ID]` | Lists saved sessions of the current workspace, or prints one session's user and assistant messages                          |
| `nc models`        | Lists the models of each harness with thinking levels, the default level, and service tiers                                 |
| `nc hand [URL]`    | Makes this machine a hand that runs a brain's Code Mode cells. `nc runner` is an alias                                      |

### exec

`nc exec` accepts every [session option](#session-options). A missing or empty prompt is an error. Before it exits, it prints `session <id>` to stderr.

```bash
# Run one prompt and keep only the reply
nc exec -m luna "Summarize the diff." > summary.md
```

### resume

`nc resume ID` is the same as `nc --resume ID`. Without an ID, it opens the session picker.

```bash
# Pick a saved session to resume
nc resume
```

### sessions

Each listed row shows the session ID, its age, its model, and its title.

| Option         | Behavior                                                                |
| -------------- | ----------------------------------------------------------------------- |
| `[ID]`         | Prints this session's messages as `## user` and `## assistant` sections |
| `--all`        | Includes sessions from every workspace                                  |
| `--home <DIR>` | Session store directory. Env: `NANOCODE_HOME`. Default: `~/.nanocode`   |

```bash
# List sessions from every workspace
nc sessions --all
```

### models

`nc models` takes no options.

```bash
# List models per harness
nc models
```

### hand

A hand dials the brain at `URL`, or listens with `--listen`. A dialing hand reconnects until the brain disconnects it.

| Option            | Behavior                                                                                                  |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| `[URL]`           | Brain endpoint to dial, such as `wss://<worker>/sessions/<name>/hands`. Required unless `--listen` is set |
| `--listen <ADDR>` | Listens on this loopback address for a brain to dial instead                                              |
| `--token <TOKEN>` | Shared secret presented to or required from the brain. Env: `NANOCODE_RUNNER_TOKEN`. Required             |
| `--name <NAME>`   | Hand name. Default: the machine's host name                                                               |
| `-C, --cd <DIR>`  | Starting directory. Default: the current directory                                                        |
| `--cua`           | Also serves computer use from the installed provider                                                      |

```bash
# Dial a local brain as build-box
NANOCODE_RUNNER_TOKEN="$TOKEN" nc hand ws://127.0.0.1:9000 --name build-box
```

## Session Options

`nc` and `nc exec` accept these options.

| Option                      | Behavior                                                                                                  |
| --------------------------- | --------------------------------------------------------------------------------------------------------- |
| `[PROMPT]`                  | Prompt to send as soon as the session is ready                                                            |
| `-m, --model <MODEL>`       | Model ID or alias from `nc models`. Env: `NANOCODE_MODEL`. Default: `claude-opus-5-5` at `xhigh` thinking |
| `--harness <codex\|claude>` | Harness whose default model to use when `--model` is absent. A `--model` of the other harness is an error |
| `-t, --thinking <LEVEL>`    | `none`, `low`, `medium`, `high`, `xhigh`, or `max`, as the model supports                                 |
| `--tier <TIER>`             | `standard`, `fast`, or `ultrafast`, as the model supports. Default: `standard`                            |
| `-C, --cd <DIR>`            | Workspace directory. Default: the current directory                                                       |
| `-r, --resume [ID]`         | Resumes a saved session. Without an ID, the interface opens a picker                                      |
| `-c, --continue`            | Resumes the most recent session in the workspace                                                          |
| `--ephemeral`               | Keeps the session in memory only. `--resume` and `--continue` reject it                                   |
| `--home <DIR>`              | Directory for sessions, history, logins, and pasted images. Env: `NANOCODE_HOME`. Default: `~/.nanocode`  |
| `--no-mouse`                | Leaves mouse capture off, so the terminal keeps native text selection                                     |
| `--no-subagents`            | Removes the subagent tools                                                                                |

```bash
# Start a throwaway session on Sonnet at high thinking
nc -m sonnet -t high --ephemeral
```

### Gateway Options

A gateway routes Codex models (`gpt-6.1-sol`, `gpt-6-luna`, `gpt-6-astra`) through a Responses gateway for the whole process, including `/new`, `/model`, and resumed sessions. Keys come from the environment and are never saved. Claude models keep their own login.

| Option                      | Behavior                                                                                                  |
| --------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--gateway <GATEWAY>`       | `openrouter`, `vercel`, `cloudflare`, or `cloudflare-gateway`. Env: `NANOCODE_GATEWAY`                    |
| `--cloudflare-account <ID>` | Cloudflare account ID for `cloudflare` and `cloudflare-gateway`. Env: `CLOUDFLARE_ACCOUNT_ID`             |
| `--cloudflare-gateway <ID>` | AI Gateway ID. Required for `cloudflare-gateway`, optional for `cloudflare`. Env: `CLOUDFLARE_GATEWAY_ID` |
| `--gateway-base-url <URL>`  | Replaces the gateway base URL, such as a Cloudflare custom domain. Requires `--gateway`                   |

| Gateway              | Credentials                                                                                     |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| `openrouter`         | `OPENROUTER_API_KEY`                                                                            |
| `vercel`             | `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN`                                                     |
| `cloudflare`         | `CLOUDFLARE_API_TOKEN`                                                                          |
| `cloudflare-gateway` | `OPENAI_API_KEY`, `CF_AIG_TOKEN` for stored keys, or `CLOUDFLARE_API_TOKEN` for Unified Billing |

```bash
# Run Luna through Vercel AI Gateway
AI_GATEWAY_API_KEY="$KEY" nc --gateway vercel -m luna
```

### Runner Options

These options attach a hand to the session. `--runner-connect` and `--runner-host` reject each other.

| Option                          | Behavior                                                                                                                       |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `--runner-connect <WS_URL>`     | Connects to a hand started with `nc hand --listen`. Requires `--runner-token`                                                  |
| `--runner-host <ADDR>`          | Listens for a hand that dials this address                                                                                     |
| `--runner-token <TOKEN>`        | Shared secret for the runner connection. Env: `NANOCODE_RUNNER_TOKEN`                                                          |
| `--runner-name <NAME>`          | Runner name, and its mount point `/<name>` in `alongside` mode. Default: `runner`, or the name the hand advertises             |
| `--runner-workspace <PATH>`     | Overrides the workspace path the hand advertises                                                                               |
| `--runner-mode <MODE>`          | `alongside` keeps local tools and mounts the hand under `/<name>`. `replace` runs every tool on the hand. Default: `alongside` |
| `--runner-call-timeout-ms <MS>` | Hard deadline for each remote tool call, in milliseconds                                                                       |

```bash
# Run every tool on a listening hand
nc --runner-connect ws://127.0.0.1:9000 --runner-token "$TOKEN" --runner-mode replace
```

## Global Options

Every command accepts these options.

| Option                      | Behavior                                                                                                 |
| --------------------------- | -------------------------------------------------------------------------------------------------------- |
| `--log <FILTER>`            | Tracing filter in `RUST_LOG` syntax for the log file and OpenTelemetry export. Env: `NANOCODE_LOG`       |
| `--log-format <FORMAT>`     | `compact`, `pretty`, or `json`. Env: `NANOCODE_LOG_FORMAT`. Default: `compact`                           |
| `--log-file <PATH>`         | Writes tracing logs to this file. Env: `NANOCODE_LOG_FILE`                                               |
| `--telemetry <LEVEL>`       | `off`, `agent`, or `all`. Env: `NANOCODE_TELEMETRY`. Default: `agent`                                    |
| `--otel-endpoint <URL>`     | OTLP/HTTP collector base URL for trace and metric export. Env: `OTEL_EXPORTER_OTLP_ENDPOINT`             |
| `--otel-environment <NAME>` | Deployment environment of exported telemetry. Env: `OTEL_DEPLOYMENT_ENVIRONMENT`. Default: `development` |
| `-h, --help`                | Prints help                                                                                              |
| `-V, --version`             | Prints the version                                                                                       |

With `--log` and no `--log-file`, the interface writes logs to `<home>/log/nanocode.log`, and the other commands write them to stderr. Traces and metrics are recorded under `<home>/log/otel/` at every telemetry level except `off`.

```bash
# Record a span for every terminal frame and export to a collector
nc --telemetry all --otel-endpoint http://localhost:4318
```

## Environment

| Variable                      | Option                              | Purpose                                                                           |
| ----------------------------- | ----------------------------------- | --------------------------------------------------------------------------------- |
| `NANOCODE_HOME`               | `--home`                            | Home directory. Default: `~/.nanocode`                                            |
| `NANOCODE_MODEL`              | `--model`                           | Model ID or alias                                                                 |
| `NANOCODE_GATEWAY`            | `--gateway`                         | Responses gateway for Codex models                                                |
| `NANOCODE_RUNNER_TOKEN`       | `--runner-token`, `nc hand --token` | Shared runner secret                                                              |
| `CLOUDFLARE_ACCOUNT_ID`       | `--cloudflare-account`              | Cloudflare account ID                                                             |
| `CLOUDFLARE_GATEWAY_ID`       | `--cloudflare-gateway`              | Cloudflare AI Gateway ID                                                          |
| `NANOCODE_LOG`                | `--log`                             | Tracing filter                                                                    |
| `NANOCODE_LOG_FORMAT`         | `--log-format`                      | Log format                                                                        |
| `NANOCODE_LOG_FILE`           | `--log-file`                        | Log file path                                                                     |
| `NANOCODE_TELEMETRY`          | `--telemetry`                       | Telemetry level                                                                   |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `--otel-endpoint`                   | OTLP/HTTP collector URL                                                           |
| `OTEL_DEPLOYMENT_ENVIRONMENT` | `--otel-environment`                | Deployment environment                                                            |
| `CLAUDE_CONFIG_DIR`           |                                     | Claude Code directory searched for an existing Claude login. Default: `~/.claude` |

The gateway credential variables are listed under [Gateway Options](#gateway-options).

```bash
# Select the model and home for every run in this shell
export NANOCODE_MODEL=haiku NANOCODE_HOME=~/.nanocode-ci
```

## Errors

`nc` prints `nanocode: <error>` to stderr and exits with status 1. Common errors:

* **Unknown model:** `--model` names no model of either harness. The message lists the known models.
* **Harness mismatch:** `--model` belongs to a different harness than `--harness`.
* **Unsupported setting:** `--thinking` or `--tier` names a level that the model does not support.
* **Missing durability:** `--resume` or `--continue` runs with `--ephemeral`.
* **No saved session:** `--continue` finds no saved session for the workspace.
* **Missing gateway key:** `--gateway` runs without its credential variable, or without `--cloudflare-account` or `--cloudflare-gateway` where required.
* **No terminal:** The interface runs without a terminal. Use `nc exec` instead.

```bash
# Fails: the Claude harness has no Luna model
nc --harness claude -m luna
```