# Headless runs
Source: https://docs.ideharmony.com/cli/run
`harmony run` runs **one Harmony Agent model turn** without a UI and exits when
the turn is over. It is the command to reach for in scripts, CI and scheduled
jobs. The turn goes through the same pipeline as the [TUI](/docs/tui): it
registers a session for the working directory, sends the prompt once, reads the
turn's events back, and closes the session when it is done.
```bash
harmony run "fix the failing tests"
echo "refactor utils" | harmony run --output jsonl
harmony run "summarize the diff" --output json --timeout 120
harmony run "audit the config" --cwd ./service --non-interactive-approval fail
```
Before the first run, set up a model once: run `harmony tui`, then `/login`
and `/model`. Without that, `harmony run` stops before any turn starts and
exits `3` with that instruction.
## Options
The prompt is the first argument. When there is none, `harmony run` reads it
from stdin. These are the only options it accepts; anything else is a usage
error (exit `2`).
| Option | Default | Meaning |
|---|---|---|
| `--cwd
` | current directory | The directory the agent's workspace is bound to |
| `--timeout ` | `600` | Turn deadline, up to `86400`. When it passes, the turn is cancelled and the run exits `7` |
| `--output text\|json\|jsonl` | `text` | Output format, described below |
| `--output-file ` | none | Write the output to a file inside the current directory instead of stdout |
| `--non-interactive-approval deny\|fail` | `deny` | What happens when the agent asks for a permission: `deny` refuses it and lets the turn continue; `fail` ends the turn |
| `--no-color` | off | Suppress the launch banner in text output |
| `--detach` | | **Refused** (exit `2`). The runtime acknowledges a turn only once it has finished, so there is no "accepted, still running" receipt to hand back, and no command can read a detached turn's result later |
**Nothing is ever approved.** There is no approval policy that grants a
permission on your behalf; a headless run cannot give consent you did not give.
There is also no hidden fallback: no other API key, subscription or model is
tried when the configured one is unavailable.
The provider, model and profile come from the setup you made in the TUI. The
run does not take them as flags.
Ctrl+C cancels the turn. The run reports `cancelled` only when the runtime
confirms the cancel; if it cannot confirm, the run says the turn may still be
running rather than claiming it stopped.
## Output
The output schema is **version 2**. Every event and the final result carry
`"schemaVersion": 2`.
- **`text`**: the assistant's reply, then a short summary: classification,
exit code, session, turn, model, event count and duration.
- **`json`**: one object, `{ "result": …, "events": [ … ] }`, printed when
the turn is over.
- **`jsonl`**: one line per event as it arrives, then a final line with
`"type": "final"` holding the result.
The final result names what ran:
| Field | Meaning |
|---|---|
| `ok`, `exitCode` | The verdict; `exitCode` matches the process exit status |
| `classification` | `success`, `failed`, `cancelled`, `timeout`, `setup-required` or `refused` |
| `stage` | The step that produced the classification, such as `runtime start` or `model turn` |
| `sessionId`, `launchIntentId`, `workspaceId`, `taskId` | The runtime session this run registered and the records it is bound to |
| `turn` | The turn's ids, from the runtime's prompt receipt |
| `text` | The assistant's reply |
| `eventCount`, `streamSettlement` | How many events were read, and whether the event stream itself carried the turn's end |
| `deniedPermissionRequests` | Permission requests this run refused |
| `cancel` | Whether a cancel was requested, and whether the runtime confirmed it |
| `runtimeClosed` | Whether the session was closed at the end |
| `error` | The `NALA_*` code, the message, and a `remediation` when there is one concrete next step |
Provider-specific data is kept under `provider`, and any payload key that
looks like a secret is replaced with `[REDACTED]`.
With the global `--json` flag, the result comes back inside the standard
[JSON envelope](/docs/cli/exit-codes#the-json-envelope) instead.
## Exit codes
`harmony run` classifies its own outcome, so a script can branch on the code.
| Code | Meaning |
|---|---|
| `0` | The turn finished |
| `2` | Usage: no prompt, an unknown option, or `--detach` |
| `3` | No model is set up, or the provider or daemon is unavailable |
| `4` | Refused: a permission was denied under `--non-interactive-approval fail`, or the billing route lock refused the turn |
| `5` | The turn failed |
| `6` | Cancelled, confirmed by the runtime |
| `7` | Timed out; the turn was cancelled at the `--timeout` deadline |
| `8` | Version or capability mismatch between the CLI and the daemon |
| `9` | Conflict: the write raced another writer |
| `10` | Anything else the run could not classify |
These codes are specific to `harmony run` and `harmony ""`. Other
commands follow the [shared table](/docs/cli/exit-codes).
## `harmony ""`
A prompt with no command runs the same single turn and prints a plain
transcript as the events arrive. It is not the TUI: for a conversation, run
`harmony` or `harmony tui`. It takes one option, `--cwd`, and has no deadline;
Ctrl+C cancels the turn the same way.
## `harmony ask` and `harmony plan` refuse
Both commands **refuse** today and exit `8` with `NALA_CAPABILITY_UNSUPPORTED`.
Nothing is submitted. `ask` promises a read-only turn and
`plan` a planning-only one, and the Harmony Agent runtime cannot enforce either
yet. Rather than run a turn that could change files, they do nothing. Use
`harmony run` for a supervised turn in the meantime.
## Related
- [CLI reference](/docs/cli)
- [Exit codes](/docs/cli/exit-codes)
- [CLI command index](/docs/cli/command-index)