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.
rayu run "summarize the changes in src/auth and list the risks"Flags that make a run script-friendly#
| Flag | Effect |
|---|---|
--json | Print one result object and nothing else |
--ndjson | Stream newline-delimited events as they happen |
--quiet (or RAYU_QUIET=1) | Suppress non-error status output |
--no-update | Skip the update check |
--no-selfdev | Skip 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 |
--trace | Log tool inputs, outputs, and token usage to stderr |
The conventional wrapper prefix is:
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:
rayu --quiet run "explain this failure and propose a fix:
$(cat error.log)"--json#
rayu --quiet run --json "reply with exactly: OK"| Field | Meaning |
|---|---|
session_id | Session the run created or resumed; use it with --resume |
provider | Provider that served the request |
model | Resolved model id |
text | Final assistant text |
usage | Token counts as the provider reported them |
rayu_credits | Credits 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:
rayu --quiet run --ndjson "fix the failing test in src/parser" | \
jq -c 'select(.type=="tool_start" or .type=="done")'| Event | Payload |
|---|---|
start | session_id, provider, model |
text_delta | text chunk |
text_replace | text — the whole message so far replaces the previous text |
text_suffix_replace | old_text, new_text — a suffix rewrite |
tool_start | id, name |
tool_input | delta — streamed tool argument JSON |
tool_exec | id, name |
tool_done | id, name, status and output summary |
tokens | Running token counts |
rayu_credits | Credit charge when the gateway reports one |
message_end | stop_reason |
session | session_id |
compaction | Context compaction started |
memory_injected | Memory was recalled for this turn |
service_tier | requested, tier, report_status |
connection_type, connection_phase | Transport details |
status_detail | Human-readable status |
upstream_provider | Which upstream actually served it |
batch_progress | Progress for batch tool runs |
error | Failure |
done | Final 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:
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:
| Variable | Effect |
|---|---|
RAYU_RUN_MCP=0 | Skip MCP registration entirely for a fast, tool-light run |
RAYU_RUN_MCP_WAIT_MS | How 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.
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#
| Code | Meaning |
|---|---|
0 | The turn completed |
1 | Anything 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#
#!/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
}
fiKeep 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:
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.jsonNotes that matter in CI:
- Store the credential as a repository secret named
RAYU_API_KEY.rayureads 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-selfdevmatters 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.0if 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#
| Lever | How |
|---|---|
| Fewer turns | RAYU_RUN_AUTO_POKE=0 |
| Smaller prompt | --tool-profile minimal, --disabled-tools, [tools] in config |
| Cheaper model | -m with a smaller model |
| No MCP startup | RAYU_RUN_MCP=0 |
| Bounded answers | Ask 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 →