Choose a machine-readable contract
Use -p for a single headless prompt. plain is for humans, json emits one final object, and streaming-json emits newline-delimited events as work arrives.
Parse fields rather than scraping prose. Capture exit status, stderr, output completeness, and the returned session ID; set time and turn bounds in the surrounding runner.
grok -p "List TODO comments" --output-format json
grok -p "Explain the architecture" --output-format streaming-jsonBuild a non-interactive safety envelope
Authenticate through the runner secret store, set the exact working directory, and allow only the tools the job needs. Avoid always-approve unless an enforced sandbox and deny policy make every possible side effect acceptable.
Pass --no-auto-update in scripts and ACP jobs so a background update does not change a reproducible run. Resume by explicit ID for multi-step jobs and persist artifacts only after redaction.
- Pin the runner image and record grok version.
- Use a read-only or strict sandbox for audits.
- Fail closed when a permission cannot be requested interactively.
grok --no-auto-update --cwd /path/to/repo --sandbox read-only -p "Audit authentication boundaries" --output-format jsonUse ACP when an application owns the UI
grok agent stdio starts an Agent Client Protocol server over JSON-RPC on stdin and stdout. The client initializes, authenticates, opens a session, sends prompts, and consumes session/update chunks rather than treating session/prompt as the assistant text.
Keep protocol framing on stdout and diagnostics on stderr. Add request IDs, timeouts, cancellation, process cleanup, and a permission strategy before embedding the agent in an IDE, bot, or orchestration service.
grok --no-auto-update agent stdio