Grok CLI
xAI Grok CLI
- grok
ACP session streams, TOML config, hooks and rules with Claude and Cursor compatibility.
- Invoke
- 4 of 6 · official
- Models
- native listing
- MCP
- toml · standard
- Agents file
- none stable
Access
- Get
getHarness("grok") - CLI
harnesses paths grok --json - Trygrok in the explorer
Grok writes an ACP update stream per session, updates.jsonl, that is the authoritative record of the conversation and its tool calls, with chat history, summaries and rewind points beside it. A local FTS5 index over titles and prompts backs its session search. Everything under ~/.grok/ moves with GROK_HOME, hence the note. It is the most thoroughly recorded session layout of the thirteen, and the most annoying to read back by hand.
It reads more of other harnesses' files than any of them: AGENTS.md, Agents.md, AGENT.md, Claude.md, CLAUDE.md, CLAUDE.local.md are all loaded, and .claude/rules/ and .cursor/rules/ are scanned through vendor compatibility, as are Claude and Cursor hook sources. -p is short for --single. Its ACP parser knows audio blocks but the runtime rejects them, so audio is false. Native X search is a tool, so tools: true is what enables it through invoke.
--sandbox read-only is stricter on Linux than the name says. Every process Grok starts loses the network there, MCP servers included. Grok's own web and X search don't notice, they run inside Grok. Your web_search from an MCP server? Dies on EAI_AGAIN. On macOS the sandbox skips that part, which is why readOnlyNetwork() answers per platform.
Capabilities and invocation
- mcp: yes
- vision: yes
- audio: no
- video: no
- tools: yes
- streaming: yes
Binary grok, evidence official. -p is short for --single; add --output-format json for structured output. --sandbox read-only is kernel-enforced (Landlock, Seatbelt) regardless of the inherited permission mode and still allows writes to ~/.grok and temp dirs; verified on Linux with 1.0.13 and 1.0.25. On Linux it also cuts the network of every child process through seccomp, MCP servers included, so their lookups die on EAI_AGAIN while Grok's own web search keeps working; seen with 1.0.41. macOS skips that part. Model selection appends --model {model}.
- advisor{}rejected
- advisor · json{ structured: true }rejected
- read-only{ readOnly: true }
-p {prompt} --sandbox read-only - read-only · json{ readOnly: true, structured: true }
-p {prompt} --sandbox read-only --output-format json - agent{ tools: true }
-p {prompt} - agent · json{ tools: true, structured: true }
-p {prompt} --output-format json
Model listing runs grok models, and a filter matches the ids locally. Prints bare ids with the default marked; verified with 1.0.41.
Paths
Templates as the registry stores them. ~, ${HOME}, ${TMPDIR} and %VAR% expand in resolve(); entries tagged with a platform are dropped on the others. Open in the explorer to see them expanded for a home directory of your choice.
config
~/.grok/config.tomlBase directory overridable with GROK_HOME.
.grok/config.toml
sessions
~/.grok/sessions/<encoded-cwd>/<session-id>/updates.jsonlAuthoritative ACP session update stream (conversation + tool calls); session dirs also hold chat_history.jsonl, summary.json, rewind_points.jsonl.
~/.grok/sessions/<encoded-cwd>/prompt_history.jsonlPer-project prompt history.
instructions
AGENTS.mdAlso accepts Agents.md, AGENT.md, Claude.md, CLAUDE.md, CLAUDE.local.md; every matching file in a directory is loaded.
.grok/rules/*.md rules scanned at each level from repo root to cwd; .claude/rules/ and .cursor/rules/ scanned via vendor compatibility.
~/.grok/rules/Global user-level rules.
skills
.grok/skills/~/.grok/skills/Global user-level skills.
commands
.grok/commands/~/.grok/commands/Global user-level slash commands.
hooks
.grok/hooks/~/.grok/hooks/JSON hook definitions (e.g. session-start.json); Claude/Cursor hook sources scanned via vendor compatibility.
Empty
promptTemplatestempThat is not the same as the feature being missing.
MCP servers
~/.grok/config.tomluser · toml · standard · mcp_servers.grok/config.tomlproject · toml · standard · mcp_servers
Detection
envVars
- GROK_SESSION_ID
- GROK_WORKSPACE_ROOT
- GROK_HOME
projectMarkers
- .grok
Persistence
- TOML - Configuration files. (official)
- JSONL - Session update streams, chat history, prompt history. (official)
- JSON - Session state files (summary.json, plan.json, signals.json). (official)
- SQLite - Local FTS5 index over session titles and prompts for sessions search. (official)
No stable user-scope instructions file, so syncAgentsFiles skips this harness.