100 lines
4.1 KiB
Markdown
100 lines
4.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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)
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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`.
|