Grok CLI Manual

Workflows and Troubleshooting

A clear goal, scope, output shape, and verification step matter more than an unnecessarily long prompt.

Resume sessions

grok sessions
grok --continue
grok --resume

--continue resumes the latest session for the current directory. --resume lets you select or restore an existing session.

Use a separate worktree

grok --worktree=feat "Implement this feature, run tests, and summarize the diff"

This is useful for experimental changes or work that should run alongside your current checkout.

Headless mode with self-checking

grok --check --max-turns 8 -p 'Diagnose the current test failure, make the smallest fix, and rerun the relevant tests'

--check adds a verification loop to a headless task. --max-turns limits the number of agent turns.

JSON output

grok --output-format json -p 'Summarize this project build and test commands'

For a stable shape:

grok \
  --json-schema '{"type":"object","properties":{"build":{"type":"string"},"test":{"type":"string"}},"required":["build","test"]}' \
  -p 'Return the build and test commands for this project'

MCP and plugins

grok mcp --help
grok plugin --help

Read the subcommand help before adding an MCP server or plugin for a project.

Common problems

Symptom	Check first
`grok models` fails	`models_base_url`, ZAI Router Key, and network connectivity
Backend or request-format error	Confirm `api_backend = "responses"` is inside the correct model block
Configuration change has no effect	Run `grok inspect` and confirm the file used by this environment
Model is missing	Check ZAI Router model permissions and name mapping
Long sessions compact too early or late	Adjust `auto_compact_threshold_percent`
`grok` command is missing	Reopen the terminal and check `PATH` and the install location

Start troubleshooting with grok inspect, grok models, and one minimal grok -p request. This quickly narrows the problem to local configuration, ZAI Router, or model inference.

Previous Permissions and Safety