> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cortex.foundation/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless and one-shot runs

> cortex exec for scripts and automation, cortex run for a single streamed answer: autonomy levels, output formats, limits and exit codes

Two commands work without a terminal to draw into, so they are safe in pipelines and scripts where the TUI would refuse to start. `cortex exec` is the headless one: an autonomy ceiling, machine-readable output, turn and time limits, and a non-zero exit when anything goes wrong. `cortex run` is the one you type yourself: one prompt, one streamed answer, with sessions and sharing.

This page covers which of the two to reach for, how autonomy works when there is nobody to answer an approval prompt, the output formats and what the result document contains, the limits you should always set, and the exit-code contract that a script has to respect. For pipeline recipes, see the [CI cookbook](/cli/ci).

| Command       | Use it for                                                                                                           |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `cortex exec` | Automation and scripts. Autonomy levels, structured output, turn and time limits. Fails closed with a non-zero exit. |
| `cortex run`  | A single request from your shell. Streams a formatted answer, continues sessions, can share the result.              |

Both create a **Cloud** session unless `CORTEX_COMPUTER` or `CORTEX_SSH_HOST` selects another host. See [Cloud, This PC, and SSH](/cli/hosts).

## `cortex exec`

### Give it a prompt

```bash theme={null}
cortex exec "explain what the storage layer does"
cortex exec -f prompt.txt
echo "review the diff" | cortex exec
```

### Autonomy

There is nobody to ask in a headless run, so the run's authority has to be decided before it starts. `--auto` is that decision:

| Level       | Allows                                                                                                                                   |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `read-only` | Reading, searching, analysing. No file changes, no commands. **Default.**                                                                |
| `low`       | Basic file operations: documentation, formatting, comments. Refused, see below                                                           |
| `medium`    | Adds package installation, builds, local git operations. Refused, see below                                                              |
| `high`      | Never asks, and allows workspace writes with network access. Its own description is git push, deployments and other sensitive operations |

```bash theme={null}
cortex exec --auto read-only "review this code for security issues"
cortex exec --auto high      "implement unit tests for the auth module"
```

Start at `read-only` and raise the level only as far as the task genuinely needs. A review job never needs write access. In this build `cortex exec` accepts `read-only` and `high` only: `--auto low` and `--auto medium` stop the run before anything is submitted, with `--auto low/medium (client risk thresholds) is not supported by the Code service contract. No turn was submitted.`

You can narrow the run further, independently of the level, by naming the tools it may use:

```bash theme={null}
cortex exec --list-tools
cortex exec --list-tools --enabled-tools Read,Grep,Glob
```

Tool names are case-sensitive, and `--list-tools` prints what a given run actually has. `--enabled-tools` and `--disabled-tools` are accepted only alongside `--list-tools`; on a run that submits a turn they stop it first, with `--enabled-tools is not supported by the Code service contract. No turn was submitted.` To narrow what a real run may do, set `--auto` and the `[permission]` table. See [Tools the agent uses](/cli/tools) and [Permission policy](/cli/policy).

<Warning>
  `--skip-permissions-unsafe` is declared on `cortex exec` but refused: it stops the run with `--skip-permissions-unsafe is not supported by the Code service contract. No turn was submitted.` It is also declared as conflicting with `--auto`, so the two cannot be passed together. There is no flag that removes permission checks from a headless run. Set the autonomy level you want, and pin the rest with the `[permission]` table.
</Warning>

### Hooks are not approvals

A hook cannot stand in for your consent. No hook can approve a tool call, and adding a hook does not make a run more permitted than its policy allows. A hook is not a way to stop one either: hooks belong to a plugin and do not fire around the tool calls a run makes. What a headless run may do is decided by `--auto`, the tool allow and deny lists, and the permission policy, before the first turn. See [Hooks](/cli/hooks) and [Permission policy](/cli/policy).

### Output formats

`-o` / `--output-format`:

| Value            | Output                                                    |
| ---------------- | --------------------------------------------------------- |
| `text`           | Human-readable. **Default.** Its shape is not a contract. |
| `json`           | One JSON document with the final result                   |
| `stream-json`    | JSON Lines, one event per line, as execution proceeds     |
| `stream-jsonrpc` | JSON-RPC streaming for multi-turn conversations           |
| `debug`          | Deprecated alias for `stream-json`                        |

```bash theme={null}
cortex exec -o json "list all TODO comments" > result.json
cortex exec -o stream-json "run the test suite" | tee run.jsonl
```

`--input-format` selects how the prompt is fed in. It takes `text`, the default; `stream-jsonrpc` for the JSON-RPC protocol; and `stream-jsonl` for one JSON object per line, one line per turn, with no envelope or ids and the connection held open between turns. `--response-format` is accepted only as `text`, which is what it already is, and `--output-schema` is refused outright. When you need a validated result document, use `-o json` with `--json-schema`.

### Add context

| Flag                                    | Effect                                      |
| --------------------------------------- | ------------------------------------------- |
| `--include <GLOB>` / `--exclude <GLOB>` | Filter the files in the context; repeatable |
| `--git-diff`                            | Include the current git diff                |
| `--url <URL>`                           | Fetch a URL into the context                |
| `--clipboard`                           | Read the clipboard                          |

### Limits

```bash theme={null}
cortex exec --timeout 1800 "refactor the storage layer"   # default 600 seconds
cortex exec --max-turns 10 "quick task"                   # default 100 turns
```

A turn is one complete request and response cycle with the model. Both defaults exist so a runaway run eventually stops, but in automation you should set them yourself: they are the difference between a failed job and a runner that hangs.

### Other flags

| Flag                      | Effect                                  |
| ------------------------- | --------------------------------------- |
| `--use-spec`              | Run through [Spec mode](/cli/plan-mode) |
| `-s`, `--session-id <ID>` | Continue an existing session            |
| `--echo`                  | Include the prompt in the output        |

A further set of flags is declared on `cortex exec` but refused before a turn is submitted, each with `<flag> is not supported by the Code service contract. No turn was submitted.`: `--skip-permissions-unsafe`, `--output-schema`, `--max-tokens`, `--frequency-penalty`, `--presence-penalty`, `--stop`, `--logprobs`, `--n`, `--best-of`, `--user`, `--suffix`, `--spec-model`, `-i`/`--image`, and `--response-format` or `-r`/`--reasoning-effort` with anything but their default. `cortex exec --help` lists what is declared; this page tells you which of it runs.

## `cortex run`

`cortex run` streams a formatted answer into your terminal and understands sessions. It is the one to use when a person is reading the output.

```bash theme={null}
cortex run "explain the release process"
cortex run --continue "now write it up as a checklist"
cortex run --session <ID> "and add the rollback steps"
cortex run --worktree --ephemeral "try the risky refactor and show me the diff"
cortex run --agent reviewer --format json "review the auth module"
cortex run -f context.md -o answer.md "turn this into a runbook"
```

| Flag                                                                   | Effect                                                                                                                      |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `--format <default/json/jsonl>`                                        | Output format; `--output` is an alias                                                                                       |
| `-c`, `--continue` / `-s`, `--session <ID>`                            | Continue the most recent session, or a named one                                                                            |
| `--agent <AGENT>`                                                      | Agent to use                                                                                                                |
| `--command <COMMAND>`                                                  | Run a predefined command instead of a prompt                                                                                |
| `-f`, `--file <PATH>`                                                  | Attach a file; repeatable                                                                                                   |
| `-C`, `--copy` / `-o`, `--output-file <PATH>`                          | Copy the answer to the clipboard, or write it to a file                                                                     |
| `--cwd <DIR>`                                                          | Working directory override                                                                                                  |
| `--worktree [DIR]`                                                     | Run in an isolated git worktree                                                                                             |
| `--plugin-dir <DIR>`                                                   | Extra plugin folder, or a single plugin; repeatable                                                                         |
| `--timeout <SECONDS>`                                                  | Time limit. `0` means no timeout, and that is the default                                                                   |
| `--dry-run`                                                            | Preview what would be sent, with estimated token counts, without executing                                                  |
| `--system <PROMPT>`                                                    | Client instructions sent as additional user context, not a service system override                                          |
| `--stream` / `--no-stream`, `-q`, `--quiet`, `--no-progress`, `--bare` | Output behaviour. `--bare` prints the result and errors and nothing else                                                    |
| `--ephemeral`                                                          | Persist no session file, so nothing is left for `cortex sessions` or `--continue`. Cannot be combined with `-c`/`--session` |
| `--json-schema`                                                        | Validate the result document against the shipped JSON Schema. Needs `--format json`                                         |
| `--bash-edit-diff`                                                     | Attach unified diffs of the files the Execute tool changed                                                                  |
| `-v`, `--verbose`                                                      | Verbose output                                                                                                              |
| `-n`, `--notification`                                                 | Desktop notification when finished                                                                                          |

`cortex run` also declares a set of flags it refuses before submitting a turn, each with `<flag> is not supported by the Code service contract. No turn was submitted.`: `--share`, `--title`, `--port`, `--add-dir`, `--schema`, `--max-tokens`, `--retry`, `--no-cache`, `-t`/`--temperature`, `--top-p`, `--top-k`, `--seed`, `--frequency-penalty`, `--presence-penalty`, `--stop`, `--logprobs`, `--n` and `--best-of`. `--attach <URL>` has its own message, `--attach is not supported by this runtime. No local session was started.` Sampling, retries and sharing are therefore not available from `cortex run` on this build.

Global options that matter in a script: `--color`, `-L`/`--log-level`, `--debug`, `-c`/`--config KEY=VALUE` (repeatable) and `-p`/`--profile`.

## Read the result

`cortex run --format json` prints one document:

```json theme={null}
{
  "type": "result",
  "session_id": "...",
  "message": "the final answer",
  "events": 12,
  "success": true,
  "interrupted": false,
  "complete": true,
  "truncated": false,
  "finish_reason": "stop"
}
```

Those four booleans are there so a parser can tell the cases apart: a run can fail, be interrupted, or be truncated, and they are not the same thing. `cortex exec -o json` prints the same idea with its own field names, including `subtype`, `is_error`, `duration_ms` and `num_turns`, so read the document your command actually produced rather than assuming a shared shape.

Continuing a session across invocations is a matter of keeping the id:

```bash theme={null}
session=$(cortex exec -o json "analyse this codebase" | jq -r '.session_id')
cortex exec -s "$session" "now focus on the auth module"
```

## Exit codes

| Code     | Meaning                                                                        |
| -------- | ------------------------------------------------------------------------------ |
| `0`      | The task completed                                                             |
| non-zero | The run failed, was interrupted, was truncated, or the service was unreachable |

A non-zero exit is the contract. Do not wrap a failing run in `|| true`, or you have built a pipeline that cannot fail.

Headless runs also fail closed when the coding service cannot be reached: the run prints `The coding service is temporarily unavailable`, exits non-zero, and never falls back to running a model locally.

## Practices worth keeping

1. **Start at `read-only`** and raise autonomy only when the task needs it.
2. **Always set `--timeout` and `--max-turns`** in anything unattended.
3. **Use a JSON format** whenever something downstream parses the output.
4. **Keep the transcript.** `-o stream-json ... | tee run.jsonl` is your audit trail.
5. **Pass credentials through the environment**, never on the command line. See [Sign in to the CLI](/cli/sign-in).

## Related

* [CI cookbook](/cli/ci), pipeline recipes and secret handling
* [Modes and permissions](/cli/modes-and-permissions), the controls `--auto` maps onto
* [Permission policy](/cli/policy), rules that apply before a run starts
* [Cloud, This PC, and SSH](/cli/hosts), where an unattended run executes
* [Command reference](/cli/reference), the supported command surface group by group