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

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 acceptEdits

To also allow deleting files in that run (and nothing else):

nova -p "Remove the old build scripts" --permission-mode acceptEdits --allow-delete

Get JSON output

Generate structured machine-readable responses:

nova -p "List the failing tests" --output-format json

Use 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 20

Continue a session

Resume previous work non-interactively:

nova -p "Now add tests for it" --continuenova -p "Next step" --resume a1b2c3
Sign 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

CodeMeaning
0Finished
1Task unfinished, not verified, or the step limit was reached
2Invalid command line
3Not signed in
4Out of credits
5--timeout reached
6Refused for lack of permission, with no other result
130Interrupted
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.

Join Discord

Need help?

Open an issue on GitHub or email support@bridgeye.com.

Get help
Bridgeye • Autonomous Software Engineering.