# Headless Runs

Run one prompt without the terminal interface, for scripts and CI, with `nc exec`.

## Overview

`nc exec` opens a session, runs one prompt to the end of its turn, and exits. The reply streams to stdout. Reasoning summaries, tool calls, warnings, and the session ID stream to stderr, so a redirect of stdout keeps only the reply.

```bash
# Save only the reply to a file
nc exec "List the TODO comments in this repository." > reply.md
```

```mermaid
flowchart LR
  script[Script or CI] --> exec[nc exec]
  exec --> stdout[/stdout: reply/]
  exec --> stderr[/stderr: reasoning, tool calls, session ID/]
  exec --> store[(~/.nanocode/sessions.jsonl)]
```

If an error stops the run, `nc exec` prints `nanocode: <error>` to stderr and exits with status 1. The interactive interface needs a terminal, so scripts use `nc exec` instead.

## Walkthrough

The steps below run a prompt, read the session ID, and continue the same session.

### Run a Prompt

`nc exec` takes the same options as `nc`. The prompt is required.

```bash
# 1. Run a prompt in another checkout on Haiku at low thinking
nc exec -C ~/src/app -m haiku -t low "Summarize the README."
```

### Capture the ID

Before it exits, `nc exec` prints `session <id>` to stderr. Capture stderr to keep the ID for a later run.

```bash
# 2. Keep the reply and the trace in separate files
nc exec "Draft a changelog entry." > entry.md 2> trace.log
grep '^session ' trace.log
```

### Continue the Session

`-r ID` continues a saved session, and `-c` continues the latest one in the workspace. If the session has interrupted turns, `nc exec` runs them first and streams them to stderr.

```bash
# 3. Ask a follow-up in the latest session of this workspace
nc exec -c "Make it shorter."
```

## Recipes

### Select Model Options

| Option             | Effect                                                                          |
| ------------------ | ------------------------------------------------------------------------------- |
| `-m`, `--model`    | Model ID or alias, also read from `NANOCODE_MODEL`                              |
| `--harness`        | `codex` or `claude`, selecting that harness's default model when `-m` is absent |
| `-t`, `--thinking` | `none`, `low`, `medium`, `high`, `xhigh`, or `max`, as the model supports       |
| `--tier`           | `standard`, `fast`, or `ultrafast`, as the model supports                       |
| `--no-subagents`   | Removes the delegation tools                                                    |

```bash
# Run on the Codex default model at medium thinking
nc exec --harness codex -t medium "Find unused dependencies."
```

### Skip the Store

`--ephemeral` keeps the session in memory and saves nothing. `-r` and `-c` need a saved session.

```bash
# Run a throwaway prompt
nc exec --ephemeral "What does this repository build?"
```

### Run in CI

A CI runner has no saved login. `--gateway` routes Codex models through a Responses gateway that reads its key from the environment and never saves it. Claude models keep their own login.

```bash
# Review the branch through OpenRouter, saving nothing
OPENROUTER_API_KEY="$OPENROUTER_API_KEY" nc exec --gateway openrouter -m luna -t low --ephemeral \
  "Review git diff origin/main...HEAD for bugs. Reply with a short list."
```

### Pick a Gateway

| Gateway              | Credentials                                                 | Also needs                                              |
| -------------------- | ----------------------------------------------------------- | ------------------------------------------------------- |
| `openrouter`         | `OPENROUTER_API_KEY`                                        |                                                         |
| `vercel`             | `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN`                 |                                                         |
| `cloudflare`         | `CLOUDFLARE_API_TOKEN`                                      | `--cloudflare-account`, optional `--cloudflare-gateway` |
| `cloudflare-gateway` | `OPENAI_API_KEY`, `CF_AIG_TOKEN`, or `CLOUDFLARE_API_TOKEN` | `--cloudflare-account` and `--cloudflare-gateway`       |

`--gateway-base-url` replaces the gateway's base URL, for example with a Cloudflare custom domain. `NANOCODE_GATEWAY` sets `--gateway` from the environment.

```bash
# Route through a Cloudflare AI Gateway with a stored provider key
CF_AIG_TOKEN="$CF_AIG_TOKEN" nc exec --gateway cloudflare-gateway \
  --cloudflare-account "$ACCOUNT" --cloudflare-gateway "$GATEWAY" -m sol "Explain the CI failure."
```

### Read Saved Sessions

`nc sessions` lists the saved sessions of the current workspace, and `--all` includes every workspace. With an ID, it prints that session's user and assistant messages as Markdown.

```bash
# Print a session's conversation
nc sessions 01970000-0000-7000-8000-000000000000
```

### Log the Run

`--log` takes a filter in `RUST_LOG` syntax and writes tracing logs to stderr, or to `--log-file`. `--log-format` selects `compact`, `pretty`, or `json`.

```bash
# Write SDK info logs as JSON to a file
nc exec --log nanocode=info --log-format json --log-file run.log "Run the tests."
```

## More

- [Terminal UI](/docs/guides/cli): Install nc, sign in, and run interactive sessions.

- [Model Gateways](/docs/guides/gateways): Route Codex models through a Responses gateway.

- [Durability](/docs/guides/durability): Journal turns and reopen sessions by ID.

- [CLI](/docs/api/cli): Every subcommand, flag, and environment variable.