Run the AI agent headlessly and in CI
Headless mode runs one prompt to completion, prints the answer, and exits. It never shows a prompt, so everything it may do must be decided up front.
champrep ai -p "list the Go files here and count them"Read the prompt from standard input with -p -:
git diff | champrep ai -p -Read-only by default
Section titled “Read-only by default”Without extra flags a headless run is read-only: the agent can read and search the workspace but cannot edit files or run commands. Anything that would need a permission prompt is refused, and the model is told why.
Allow more with either flag:
| Flag | Effect |
|---|---|
--allowed-tools RULES | Pre-approve specific rules for this run only. Calls not covered by a rule are refused. |
--permission-mode accept-edits | Allow file edits inside the workspace. Commands still need an allow rule. |
champrep ai -p "fix the failing test" \ --allowed-tools "local_edit_file(src/**),local_bash(go test*)"Rules use the syntax described in
Allow and deny rules. Separate rules
with commas or spaces, or repeat the flag. When you use either flag, rules in
your user settings file also apply, and deny rules from project settings files
always apply. Allow rules from project settings files, and defaultMode from
any settings file, are not used in headless runs.
Actions that change data in your CHAMPREP services are never approved in headless mode. They stay pending, and the run prints the action ID so you can approve or reject it in the CHAMPREP web app.
Other options
Section titled “Other options”| Flag | Effect |
|---|---|
--output text | Default. The answer goes to standard output; tool activity goes to standard error. |
--output json | Stream NDJSON events to standard output. --json has the same effect when --output is not set. |
--max-turns N | Stop after N model turns. Reaching the limit ends the run with an error. |
--model NAME | auto (default), a platform model ID, or the name of a model you registered. |
--add-dir PATH | Add another directory to the workspace. Repeatable. |
--verbose | Also print status lines in text output. |
JSON output
Section titled “JSON output”With --output json, every event is one JSON object per line. Events include
the streamed answer text, CHAMPREP tool calls and results, local tool events
(local_tool_start, local_tool_result, local_resume), and approvals. The
last line is always one of:
{"type":"local_result","text":"There are 42 Go files.","conversation_id":"CONVERSATION_ID","suspensions":1,"model":"MODEL_ID","input_tokens":1234,"output_tokens":56}{"type":"local_error","code":"ERROR_CODE","message":"Explanation of the failure"}Parse the last line for the result, and treat other event types you do not recognise as informational.
Exit codes
Section titled “Exit codes”A successful run exits with 0. Failures use the standard
CLI exit codes, for example 3 when sign-in is
missing or invalid and 5 when a limit was reached. Refusals print a hint on
standard error, such as a plan that does not include the agent or a
per-minute limit with the number of seconds to wait. Pressing Ctrl+C stops
the run.
Use an API key in CI
Section titled “Use an API key in CI”-
Create a key that includes the
ai:agentscope, plus the scopes of any otherchamprepcommands the job runs.ai:agentmust be selected by name; broader scopes alone do not allow local tools.Terminal window champrep keys create --name "ci-review" --scope ai:agent -
Store it as a masked, protected CI secret named
CHAMPREP_TOKEN. The CLI uses it directly and does not need a keychain. -
Run the agent with only the permissions the job needs.
ai-review: script: - champrep ai -p "review the changes in this merge request and list problems by severity" --output json --max-turns 20 > review.ndjson - tail -n 1 review.ndjsonCommands the agent runs never receive CHAMPREP_TOKEN or any other
CHAMPREP_* variable. To keep job state away from your runner’s home
directory, set CHAMPREP_CONFIG_DIR to a temporary directory.
See API keys for CLI automation for rotation and review, and Plans and limits for how CI runs count toward your limits.