Headless

quox --print sends one message, prints the answer and exits. Use it in scripts and CI.

quox --print "summarise what changed in the fleet today"

Pipe the prompt in instead:

git diff --stat | quox --print "explain this change"

If you give no prompt, or -, it reads standard input. Put -- before a prompt that starts with -. --print can come after other flags.

Options

Option	What it does
--print [prompt]	Run one turn and exit.
--output text|json	text (default) prints the answer. json prints one JSON event per line, then a summary line.
--conversation <id>	Continue an existing conversation.
--turn-id <id>	Set the turn id, so a retry is recognisable.
--timeout <seconds>	Ask the server to stop after this long. If it does not confirm within a few seconds, Quox stops listening and reports the turn as abandoned.
--service-key	Authenticate with an ambient service key. Without this flag, a service key is never used.
-p, --profile <name>	Use a specific profile.

Identity

Headless runs as you. It uses your signed-in profile and never falls back to an ambient service key found in the environment. If you are not signed in, it exits with code 4 rather than quietly running as a service. To run as a service on purpose, pass --service-key.

JSON output

With --output json, every event is one line. The last line is a summary:

{"type":"summary","status":"completed","turn_id":"...","conversation_id":"...","duration_ms":4210,"server_stopped":false,"tools":2,"approvals":0,"receipts":[4069513]}

Read the status and receipts from the last line:

quox --print --output json "check the web hosts" | tail -n 1 | jq '{status, receipts}'

Exit codes

Code	Meaning
0	Completed.
1	Other.
2	Held for approval.
3	Interrupted or abandoned.
4	Not signed in.
5	Ended without server confirmation.

Generated from the quox client at cb294889b.

Exit code 2 is not an error in the usual sense. The work is paused, not failed. Approve it in the dashboard or in quox, then continue the conversation with --conversation <id>.

Exit code 5 means the stream ended before the server confirmed how the turn finished. Treat the outcome as unknown and check the conversation.