Headless & Agent Mode
Run Grok from scripts (headless) or inside editors (ACP)—after you can already ship in the normal screen.
Finish a ship walkthrough in the normal Grok screen first. Headless and ACP build on that skill—they do not replace learning chat + tools + verify.
Two modes outside the normal screen
Headless
grok -p "…" — one prompt (or a script). Tools may run. Grok prints text/JSON and exits.
Agent mode (ACP)
A long-running process your editor talks to. Example: grok agent stdio.
Headless flags (ideas that stay useful)
Grok Build is still Beta—flag names can change. Check grok --help or /docs before you rely on one. These ideas stay useful even if a name shifts:
| Need | Typical flag / idea |
|---|---|
| One-shot prompt | -p / --single |
| Machine-readable output | --output-format json or streaming-json |
| Skip prompts (trusted CI) | --always-approve / --yolo |
| Cap runaway loops | --max-turns N |
| Limit tools | --tools allowlist / --disallowed-tools denylist |
| Working directory | --cwd |
| Extra rules text | --rules "…" |
| Sandbox profile | --sandbox workspace|read-only|strict |
| Session continuity | -c continue / -r resume |
| CI hygiene | --no-auto-update |
| Feature offs | optional “turn off subagents / memory” flags when your version lists them |
cd ~/projects/my-app
grok -p "Summarize what this repo does in 5 bullets" --output-format plain
# CI-shaped sketch (tighten deny + sandbox in real pipelines)
grok -p "Review git diff for security issues" \\
--output-format json \\
--always-approve \\
--max-turns 12 \\
--no-auto-updateAgent mode (ACP)
grok agent --always-approve stdio
# or serve over a local port when your client needs itYour IDE extension starts this process. Daily product building still uses interactive grok unless you live in an ACP client.
Automation safety stack
- API key auth for non-browser environments
- Always-approve only with deny rules + sandbox + max-turns
- Never log secrets in prompts that CI archives
- Prefer read-only tool sets for review jobs
Lab
- From a throwaway folder, run a headless summarize prompt (no YOLO required if read-only).
- Re-run with
--output-format jsonand open the JSON in a text editor—find the main text field. - Write which three flags you’d lock for a real CI review job.
You can run grok -p successfully and name max-turns, output format, and always-approve as intentional choices—not defaults you ignore.