Grok Build Headless Mode for Scripts and CI
By CodeAgentSwarm · Updated October 31, 2026
grok -p (single-turn) prints a response and exits, which is what you want in scripts and CI. Agent subcommands expose stdio and other integration modes for editors and custom harnesses.
Grok Build is xAI's coding CLI (grok), not the Grok chatbot.Single-turn headless
export XAI_API_KEY="xai-..."
grok -p "List the top three risks in this repo"
grok -p "Summarize git diff" --output-format jsonOutput formats include plain (default), json, and streaming-json; the JSON output carries a sessionId you can pass to -r for a follow-up step. In CI, use --permission-mode dontAsk with explicit --allow rules so anything you did not allow is denied instead of waiting on a prompt, cap the run with --max-turns, and add --no-auto-update to skip update checks. The headless docs list every flag.
Never bake production API keys into public logs. Prefer CI secrets and least-privilege sandboxes (--sandbox when appropriate).
Agent mode
grok agent exposes non-TUI runtimes (stdio, headless websocket, serve, leader) that speak the Agent Client Protocol (ACP). grok agent stdio is the one most editors and SDKs use. Use these when embedding Grok in an IDE bridge or multi-client setup. See grok agent --help for the current surface.
Headless vs CodeAgentSwarm
Headless is for machines. CodeAgentSwarm is for humans supervising interactive CLIs. They complement: CI runs grok -p, developers swarm interactive grok sessions in CAS.
FAQ
How do I run Grok Build in CI?
Set XAI_API_KEY and use grok -p with --permission-mode dontAsk plus --allow rules for the commands the job needs. Add --no-auto-update, and prefer json output when a script must parse results.
Is -p the same as agent mode?
No. -p is a single-turn CLI helper. grok agent targets longer integrations over stdio/websockets.