Docs/Automation
Print mode & JSON
Run Gray headless from scripts, CI and other agents: one-shot prompts, NDJSON progress events, typed error codes, exit classes and budgets.
Source: crates/gray/src/print.rs
$gray -p "fix the failing test"$git diff | gray -p "write a commit message for this"$gray -p "summarize the repo" --json
-p runs one prompt, streams the answer to stdout, records the session, and exits. Unlike the REPL, print mode scrubs secrets before writing the transcript.
--json
--json writes one JSON record per line: progress records as the turn runs, then a final result or error.
| progress phase | When |
|---|---|
| generating | the model started answering |
| thinking | batched reasoning text, when shown |
| tool_started · tool_ran · tool_finished | a tool call's lifecycle, with tool, call_id, detail and output |
| provider_retry | a stream error the provider layer is retrying |
| compacted | context was compacted mid-run |
| persisting | the turn ended and is being saved |
Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | the turn failed — don't retry |
| 3 | provider or network death — retrying usually succeeds |
The error record carries code, retryable, message, and a hint naming the command that fixes it, so harnesses branch on the class instead of parsing prose. Codes: auth_failed, rate_limited, bad_request, context_overflow, server_error, stream_broken, connection_failed, timeout, loop_detected, cancelled, serialization, turn_failed.
Budgets & structured input
| Flag | Meaning |
|---|---|
| --max-requests N | stop after N provider requests, compaction included |
| --input-price · --output-price | USD per million tokens, for budget accounting |
| --input-json PATH | read a versioned input envelope from a file, or - for stdin |
Join the Discord
Chat with the people building and running Gray. Show what you made with it.
Join Discord →