Grok Build Headless Mode for Scripts and CI
Updated July 28, 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. Pair with --max-turns and permission flags carefully in CI so the agent cannot hang on prompts.
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). 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
Set XAI_API_KEY and use grok -p with a non-interactive permission mode. Prefer json output when a script must parse results.
No. -p is a single-turn CLI helper. grok agent targets longer integrations over stdio/websockets.
Use headless Grok Build for CI; use CodeAgentSwarm when humans need to supervise long interactive sessions.