Back
Advanced // Headless Mode
Headless Mode
Docs › Advanced › Headless Mode
Headless Mode
Run NOVA for one task and exit, with no interactive session. This is useful for scripts, CI and scheduled jobs.
Run one task
bash
nova -p "Summarise what this project does"
Pipe input in
bash
git diff | nova -p "Write a commit message for this"
cat error.log | nova -p "Why is this failing?"
echo "Explain the build setup" | nova -p
cat error.log | nova -p "Why is this failing?"
echo "Explain the build setup" | nova -p
Allow changes
With nobody there to ask, anything that needs approval is refused. In the default mode that includes edits. To allow them:
nova -p "Fix the lint errors" --permission-mode acceptEditsTo also allow deleting files in that run (and nothing else):
nova -p "Remove the old build scripts" --permission-mode acceptEdits --allow-deleteGet JSON output
Generate structured machine-readable responses:
nova -p "List the failing tests" --output-format jsonUse stream-json to get events as they happen.
Keep a job bounded
Cap duration and step count in CI environments:
nova -p "Fix the flaky test" --timeout 600 --max-turns 20Continue a session
Resume previous work non-interactively:
nova -p "Now add tests for it" --continuenova -p "Next step" --resume a1b2c3Sign in first:Run
nova login once on the machine before using nova -p. If you're not signed in, the run exits with code 3.Check the exit code
| Code | Meaning |
|---|---|
| 0 | Finished |
| 1 | Task unfinished, not verified, or the step limit was reached |
| 2 | Invalid command line |
| 3 | Not signed in |
| 4 | Out of credits |
| 5 | --timeout reached |
| 6 | Refused for lack of permission, with no other result |
| 130 | Interrupted |
Note:Exit code
0 doesn't always mean files changed. If an edit was refused and NOVA explained why, the run still exits 0. Check the Changed line in NOVA's record.All options are listed in Options & Exit Codes.
Join our Discord
Chat with our engineers and become part of the active NOVA developer community.
Need help?
Open an issue on GitHub or email support@bridgeye.com.