Grok Build CLI — headless reference

Verified against grok 0.2.93 (stable channel), 2026-07-09. Re-verify with grok --help after major version bumps — flags mirror Claude Code's.

One-shot headless run

grok -p "prompt" --output-format json
grok --prompt-file task.md --output-format json   # preferred: no shell-quoting issues

⚠️ grok agent is NOT a one-shot command — it runs the agent as a stdio/WebSocket server for SDK/ACP integrations. Always use top-level grok -p / --prompt-file.

JSON output shape (verified)

{
  "text": "final response text",
  "stopReason": "EndTurn",
  "sessionId": "019f470d-3e02-7601-b726-1133cc72ef76",
  "requestId": "…",
  "thought": "…"
}

sessionId is the handle for fix-ups.

POSIX: grok --prompt-file task.md --output-format json | python3 -c "import json,sys;print(json.load(sys.stdin)['sessionId'])"
Windows (PowerShell): grok --prompt-file task.md --output-format json | ConvertFrom-Json | Select-Object -ExpandProperty sessionId

stopReason: "Cancelled" with empty text means a tool call hit a permission gate and was auto-cancelled headlessly — you forgot --always-approve (see below).

Permissions — the headless gotcha

Use --always-approve for headless dispatch. Do NOT rely on --permission-mode acceptEdits.

Verified 2026-07-09: --permission-mode acceptEdits FAILS headlessly — the edit tool hits a permission gate with no interactive approver, and the run returns stopReason: "Cancelled" with no file change. --always-approve auto-approves BOTH edits AND shell commands in one flag (Grok ran the acceptance test itself in the same run). This is safe in the grok-build workflow because dispatch happens on a clean tree, the task spec constrains scope, and the orchestrator reviews the full diff before committing.

Optional hardening: --sandbox <profile> (env GROK_SANDBOX) restricts filesystem and network access — layer it on for untrusted repos.

Resume / fix-up

grok --resume <sessionId> -p "specific feedback" --always-approve --output-format json

Verified: the resumed session retains full context — it knows the repo and files touched without re-explanation. Pass only the specific feedback, not the whole task again.

Self-verification (`--check`) — opt-in only

--check appends a self-verification loop: Grok spawns a verifier subagent that emits a checklist, action trace, scope/edge-case evaluation, and its own VERDICT: PASS.

Verified: correct but ~doubles wall-clock (a trivial task went from a few seconds to ~48s) and adds token cost, undercutting Grok's speed/cost advantage. Skip it by default — the orchestrator's review gate is the authority. Add --check only for high-stakes tasks where you want Grok to self-correct before review.

Update check (session preflight)

grok update --check --json
# → {"currentVersion":"0.2.93","latestVersion":"0.2.93","updateAvailable":false,"channel":"stable",…}
grok update        # installs latest stable

Key flags

Flag	Purpose
`--always-approve`	Auto-approve all tool executions (edits + shell). Required for headless.
`--permission-mode <m>`	`default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan` — but see gotcha above
`--allow` / `--deny`	Fine-grained permission rules (Claude Code `--allowedTools` syntax)
`--max-turns <N>`	Turn cap — always set for headless runs
`--check`	Appends a self-verification loop (opt-in; see above)
`--worktree[=name]`	Run in a fresh git worktree (parallel tasks)
`--json-schema '<schema>'`	Constrain final output to a JSON Schema
`-m <model>`	`grok-4.5` (default) or `grok-composer-2.5-fast`
`--cwd <dir>`	Working directory for the run
`--best-of-n <N>`	Run N ways in parallel, pick best (headless)

Install & auth

Install / update: follow xAI's Grok CLI install docs for your OS; verify with grok --version. Works on macOS, Linux, and Windows (PowerShell).
Auth: grok.com subscription OAuth (grok login / grok logout). Check with grok models.
Models available: grok-4.5 (default), grok-composer-2.5-fast.

4.1 KiB Raw Blame History