---
title: "Non-interactive use and CI"
---

# Non-interactive use and CI

Run the CLI once without the interactive interface, grant what the task needs, read text or JSON output, and use exit codes in scripts and CI.

`-p` (`--print`) runs one prompt to completion and exits. The prompt comes from the arguments, from standard input, or both (standard input is appended):

```bash
neuralinverse -p "explain src/billing/invoice.ts"
cat error.log | neuralinverse -p "what is causing this?"
git diff | neuralinverse -p "review this diff for bugs" --output-format json
```

`-p` needs a usable provider; without one it exits with an error that names the variables to set.

## Grant what the task needs

There is nobody to answer, so anything that would ask is **denied**, and the model is told how to proceed. Grant what the task needs with a mode and rules:

```bash
neuralinverse -p "fix the type errors" --mode auto-edit --allow "run_shell(npx tsc *)"
neuralinverse -p "fix the failing lint errors" --mode auto-edit --allow "run_shell(npm run lint *)"
```

Some things cannot be granted in a non-interactive run:

- An approval your organisation's governance asks for is a refusal, unless an approval of exactly that action, signed under the policy's approval rule, is in `.neuralinverse/records/`.
- If the governance policy requires a work item, pass `--intent <ref>`; headless runs are refused without one.
- Flashing hardware (`fw_flash`) is always denied.
- Accepting Team memory and acknowledging overlaps are refused.

See [Permissions and modes](https://neuralinverse.com/docs/cli/permissions/).

## Output formats

| `--output-format` | Output |
|---|---|
| `text` (default) | The final answer on standard output. Add `--verbose` for progress on standard error |
| `json` | One result object |
| `stream-json` | One JSON object per line: an `init` line, then every agent event, then the `result` line |

The `json` result:

```json
{"type":"result","subtype":"success","session_id":"…","result":"…","is_error":false,"stop_reason":"end_turn","num_turns":3,"usage":{},"cost_usd":0.0,"duration_ms":0}
```

`stream-json` events: `turn_start`, `text_delta`, `assistant_message`, `tool_call`, `tool_progress`, `tool_result`, `tool_denied`, `retry`, `compacted`, `usage`, `notice`, `done`. The same events are used by the [SDK and the server API](https://neuralinverse.com/docs/cli/sdk/).

Pass model output to later steps through environment variables or files, not by pasting it into a shell command, so that generated text can never run as code.

## Limits

| Flag | Meaning |
|---|---|
| `--max-turns <n>` | Maximum model turns per prompt (the `maxTurns` setting defaults to 200) |
| `--max-cost <usd>` | Stop once the session's estimated cost reaches this. Exit code 3 with `--print` |
| `--max-time <minutes>` | Stop once the session has run this long. Exit code 3 with `--print` |

More limits (tokens, tool calls, per prompt) are in the `budget` setting; see [Providers and models](https://neuralinverse.com/docs/cli/models/#budgets).

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error, turn limit or refusal |
| 2 | Invalid usage |
| 3 | The cost or time limit was reached (with `--print`) |
| 130 | Interrupted |

The CLI's automation guide lists only 0, 1, 2 and 130; code 3 comes from the `--max-cost` and `--max-time` options.

## Sessions

Each run is saved. Continue it with `--continue` (the latest in this folder) or `--resume <id>`. Use `--no-session-persistence` for throwaway runs.

## Other useful flags

| Flag | Meaning |
|---|---|
| `-m, --model <provider/model>` | Model to use |
| `-C, --cwd <dir>` | Run as if started in that folder |
| `--add-dir <dir>` | Let tools use another folder (repeatable) |
| `--config <file>` | Load an extra settings file (repeatable) |
| `--mcp-config <file>`, `--no-mcp` | Load MCP servers from a file, or start none |
| `--append-system-prompt <text>` | Extra instructions for the system prompt |
| `--reasoning <level>` | `off`, `low`, `medium`, `high` |
| `--debug` | Print diagnostic details on errors |

The full list is in the [command reference](https://neuralinverse.com/docs/cli/reference/).

## In CI

- Install with `npm install -g @neuralinverse/cli`, the [standalone binary](https://neuralinverse.com/docs/cli/install/), or the container image `ghcr.io/neuralinverse/neuralinverse-cli`.
- Pass provider credentials as environment variables (for example `ANTHROPIC_API_KEY`). Project settings in `.neuralinverse/settings.json` (providers, MCP servers, hooks, rules) apply as they do locally.
- The daily version check is off when `CI` is set.
- Treat text from issues, comments and pull requests as untrusted input; keep the mode `read-only` or tightly scoped with `--allow`.

A minimal script without any CI-specific integration:

```bash
npm install -g @neuralinverse/cli
neuralinverse -p "fix the failing test" --mode auto-edit --allow "run_shell(npm test *)" --output-format json > result.json
node -e 'const r = require("./result.json"); console.log(r.result); process.exit(r.is_error ? 1 : 0)'
```

For GitHub Actions there is a ready-made action; see [GitHub](https://neuralinverse.com/docs/cli/github/#the-github-action). For unattended work over many turns, see [Goals, team runs and schedules](https://neuralinverse.com/docs/cli/autonomy/).