Skip to content
Documentation

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.

Terminal window
champrep ai -p "list the Go files here and count them"

Read the prompt from standard input with -p -:

Terminal window
git diff | champrep ai -p -

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:

FlagEffect
--allowed-tools RULESPre-approve specific rules for this run only. Calls not covered by a rule are refused.
--permission-mode accept-editsAllow file edits inside the workspace. Commands still need an allow rule.
Terminal window
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.

FlagEffect
--output textDefault. The answer goes to standard output; tool activity goes to standard error.
--output jsonStream NDJSON events to standard output. --json has the same effect when --output is not set.
--max-turns NStop after N model turns. Reaching the limit ends the run with an error.
--model NAMEauto (default), a platform model ID, or the name of a model you registered.
--add-dir PATHAdd another directory to the workspace. Repeatable.
--verboseAlso print status lines in text 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.

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.

  1. Create a key that includes the ai:agent scope, plus the scopes of any other champrep commands the job runs. ai:agent must be selected by name; broader scopes alone do not allow local tools.

    Terminal window
    champrep keys create --name "ci-review" --scope ai:agent
  2. Store it as a masked, protected CI secret named CHAMPREP_TOKEN. The CLI uses it directly and does not need a keychain.

  3. 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.ndjson

Commands 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.