Headless & CI
Guides

Headless & CI

30. Headless & CI#

rayu run sends one message, prints the answer, and exits. It is the interface for scripts, cron jobs, git hooks, and CI: no terminal UI, no interactive prompt, no server left behind.

bash
rayu run "summarize the changes in src/auth and list the risks"

Flags that make a run script-friendly#

FlagEffect
--jsonPrint one result object and nothing else
--ndjsonStream newline-delimited events as they happen
--quiet (or RAYU_QUIET=1)Suppress non-error status output
--no-updateSkip the update check
--no-selfdevSkip repository auto-detection
-m, --model <id>Pin the model
-p, --provider <id>Pin the provider
--resume <id>Continue an existing session
-C, --cwd <dir>Run as if started in another directory
--tool-profile <p>full, minimal/lite, or none
--tools <list>Explicit allow-list, e.g. bash,read,write,apply_patch
--disabled-tools <list>Hide tools after the profile is applied
--mcp-tools <mode>auto, eager, or deferred
--traceLog tool inputs, outputs, and token usage to stderr

The conventional wrapper prefix is:

bash
rayu --quiet --no-update --no-selfdev run "..." 

--quiet keeps stderr empty unless something is actually wrong, which is what you want in a pipeline.

rayu run takes the message as an argument only. There is no stdin prompt mode, so pipe a file through the argument instead:

bash
rayu --quiet run "explain this failure and propose a fix:

$(cat error.log)"

--json#

rayu --quiet run --json "reply with exactly: OK"
FieldMeaning
session_idSession the run created or resumed; use it with --resume
providerProvider that served the request
modelResolved model id
textFinal assistant text
usageToken counts as the provider reported them
rayu_creditsCredits charged. Absent for BYO-key providers and older gateways, so "no charge reported" is distinguishable from a real zero

--json always prints the pretty-printed object to stdout. Errors go to stderr and the process exits non-zero, so jq -e and set -e both behave.

--ndjson#

--ndjson streams events while the turn runs, which is what you want for a progress UI or a log that shows work as it happens:

bash
rayu --quiet run --ndjson "fix the failing test in src/parser" | \
  jq -c 'select(.type=="tool_start" or .type=="done")'
EventPayload
startsession_id, provider, model
text_deltatext chunk
text_replacetext — the whole message so far replaces the previous text
text_suffix_replaceold_text, new_text — a suffix rewrite
tool_startid, name
tool_inputdelta — streamed tool argument JSON
tool_execid, name
tool_doneid, name, status and output summary
tokensRunning token counts
rayu_creditsCredit charge when the gateway reports one
message_endstop_reason
sessionsession_id
compactionContext compaction started
memory_injectedMemory was recalled for this turn
service_tierrequested, tier, report_status
connection_type, connection_phaseTransport details
status_detailHuman-readable status
upstream_providerWhich upstream actually served it
batch_progressProgress for batch tool runs
errorFailure
doneFinal text, usage, session_id, tier fields, optional rayu_credits

The last line is always done on success. Parse it for the answer, or read text_delta events for live output.

service_tier_report_status values are not_reported, unresolved, reported_match, reported_mismatch. They compare provider metadata only, so do not infer billing or routing from them.

Sessions in scripts#

rayu run writes a normal session transcript, so a later call can continue with the same context:

bash
session=$(rayu --quiet run --json "audit the API routes" | jq -r .session_id)
rayu --quiet run --json --resume "$session" "now write the tests for the two you flagged"

Keep the run in one working directory: sessions and project context are keyed to it. Use -C when a script runs from somewhere else.

MCP in headless runs#

rayu run loads MCP servers from ~/.rayu/mcp.json, so mcp__* tools work the same as in the TUI. Two knobs matter for latency:

VariableEffect
RAYU_RUN_MCP=0Skip MCP registration entirely for a fast, tool-light run
RAYU_RUN_MCP_WAIT_MSHow long to wait for a cold-cache server to publish its tools before the single turn starts (default 5000, 0 disables)

A warm cache costs nothing: cached schemas are advertised immediately. See MCP servers.

Auto-poke#

After the first turn, rayu run may continue on its own when the todo list is still open or the model stopped short. That is the auto_poke feature. It is on by default and bounded, but it means a scripted run can spend more than one turn.

bash
RAYU_RUN_AUTO_POKE=0 rayu --quiet run --json "report only, change nothing"

Disable it when you are counting turns or credits exactly.

Exit codes#

CodeMeaning
0The turn completed
1Anything else: bad arguments, not signed in, provider error, tool failure that ended the run

rayu run does not signal "the model finished but disliked the task" with a special code. If a script needs a verdict, ask for JSON in the answer and parse .text, or use a turn_end hook that records RAYU_HOOK_STATUS.

Git hooks and pre-commit#

bash
#!/usr/bin/env bash
# .git/hooks/pre-commit
set -euo pipefail
if ! git diff --cached --quiet -- '*.rs'; then
  staged=$(git diff --cached -- '*.rs')
  rayu --quiet --no-update --no-selfdev run --json \
    "review this staged Rust diff for bugs. Answer with PASS or FAIL and one line of reason:

$staged" | jq -e '.text | startswith("PASS")' >/dev/null || {
      echo "rayu review failed; run 'rayu run \"review my staged diff\"' to see why"
      exit 1
    }
fi

Keep a hook like this advisory if it costs credits on every commit. A cheaper arrangement is a post_tool_feedback hook or a manual /review.

GitHub Actions#

The v3 binary installs from the same script as everywhere else, so a workflow is three steps and no npm:

yaml
name: Rayu
on:
  issue_comment:
    types: [created]

jobs:
  rayu:
    if: contains(github.event.comment.body, '@rayu') && github.event.issue.pull_request == null
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v4

      - name: Install RayuCode
        run: curl -fsSL https://rayucode.com/install | bash -s -- --no-modify-path

      - name: Run Rayu
        env:
          RAYU_API_KEY: ${{ secrets.RAYU_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          "$HOME/.local/bin/rayu" --quiet --no-update --no-selfdev run --json \
            "${{ github.event.comment.body }}" > result.json
          jq -r .text result.json

Notes that matter in CI:

  • Store the credential as a repository secret named RAYU_API_KEY. rayu reads it from the environment, so no login step is needed.
  • The installer never writes to a system directory; the binary lands in ~/.local/bin.
  • --no-selfdev matters on a checkout of the RayuCode repository itself, where auto-detection would otherwise switch on self-dev mode.
  • Pin the version with --version v3.0.0 if reproducibility matters more than freshness.
  • A workflow comment trigger runs code from the comment body. Gate it on author_association (OWNER, MEMBER, COLLABORATOR) before giving the job a write token.

The legacy Node CLI still has a published GitHub Action (Choeng-Rayu/rayu-cli/rayu-action@main) that installs @rayu-dev/rayu-cli from npm. That action targets the v2 line and is not used by v3 installations.

Cost control#

LeverHow
Fewer turnsRAYU_RUN_AUTO_POKE=0
Smaller prompt--tool-profile minimal, --disabled-tools, [tools] in config
Cheaper model-m with a smaller model
No MCP startupRAYU_RUN_MCP=0
Bounded answersAsk for a fixed shape in the prompt and check .text

There is no --max-turns or --max-budget-usd flag in v3. Bound a run with timeout(1) from the shell and with RAYU_RUN_AUTO_POKE=0 for turns.

Next#

Next: IDEs & terminals →