-p (--print) runs one prompt to completion and exits. The prompt comes from the arguments, from standard input, or both (standard input is appended):
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:
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.
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:
{"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.
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.
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.
In CI
- Install with
npm install -g @neuralinverse/cli, the standalone binary, or the container imageghcr.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
CIis set. - Treat text from issues, comments and pull requests as untrusted input; keep the mode
read-onlyor tightly scoped with--allow.
A minimal script without any CI-specific integration:
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. For unattended work over many turns, see Goals, team runs and schedules.