1. Pick the execution surface
Use the root command for interactive work or a bounded single turn. Use agent transports only when another process, editor, or service owns the conversation lifecycle.
- grok opens the terminal interface.
- -p/--single prints one response and exits.
- agent stdio speaks ACP; headless and serve are long-running integration surfaces.
grok -p "Summarize the staged changes" --output-format json --max-turns 42. Run headless and transport modes deliberately
stdio is suited to an ACP host. serve opens a WebSocket endpoint and therefore needs an explicit bind decision and secret handling. Headless relay mode participates in the shared agent architecture.
- Prefer loopback binding unless remote access is intentional.
- Never place generated secrets in shell history, logs, or documentation.
- Treat leader lifecycle operations as shared-process changes.
grok agent stdio
# or, for a local WebSocket endpoint
grok agent serve --bind 127.0.0.1:24193. Make permissions and sandboxing explicit
Automation should narrow the allowed work rather than erase the approval boundary. Root options control approval policy, sandbox choice, turn count, tool sets, planning, and output format.
- Use read-only or sandboxed modes for inspection.
- Review any always-approve or bypass option before use.
- Bound CI work with max turns and machine-readable output.
grok -p "Inspect the repository and report only" --permission-mode default --sandbox read-only --max-turns 34. Manage MCP as a lifecycle
An MCP server adds a new external capability. Add it at the narrowest scope, list the resolved entry, and diagnose it before relying on it.
- Project scope writes project configuration.
- Review command, URL, environment-name mapping, and working directory.
- Doctor output may contain paths; sanitize before sharing.
grok mcp list --json
grok mcp doctor --json5. Inspect plugins and marketplaces before trust
Marketplace provenance, plugin validation, installation, and enablement are separate decisions. Structural validation does not make third-party code safe.
- List marketplace sources first.
- Validate a local checkout before installation.
- Inspect plugin details and contributed hooks, skills, agents, and MCP servers.
grok plugin marketplace list --json
grok plugin validate /path/to/plugin
grok plugin details <name>6. Preserve session history intentionally
List or search persisted sessions before resuming. Resume continues the original lineage; fork when experimentation must not alter that lineage.
- Session titles and transcripts may be sensitive.
- Export and trace create shareable artifacts; review them first.
- Delete is destructive even when local.
grok sessions search "migration" --limit 10
grok --resume <session-id>
# preserve the original lineage
grok --resume <session-id> --fork-session7. Treat worktrees as real Git state
Grok-managed worktrees can contain dirty or unpushed work. List and inspect before removal; use garbage-collection dry runs as the default.
- show resolves an ID or path.
- rm can remove multiple worktrees and deserves review.
- db rebuild changes local indexing state, not Git history.
grok worktree list --json
grok worktree gc --dry-run8. Diagnose before changing the machine
doctor and inspect collect different evidence. Capture JSON diagnostics first, then review the repairs proposed by doctor fix.
- Keep local paths and environment-derived details out of public issues.
- Use update only after reading release changes.
- Completions and setup alter shell integration.
grok doctor --json
grok inspect --json
grok doctor fix9. Use TUI slash commands as interactive controls
Slash commands manage the current terminal session, memory, extensions, models, plans, background tasks, and UI state. They are not grok shell subcommands.
- Check the availability badge in the exhaustive reference.
- Source-preview workflow controls may not exist in the installed release.
- Deletion, sharing, memory flushes, and always-approve toggles change state.
/session-info
/context
/model
/plugins
/mcps
/doctor10. Configure by schema, keep values private
The reference publishes key names, types, enum choices, and documented defaults. It deliberately does not inspect local config or environment values.
- Keep deployment keys, tokens, and cookies outside committed files.
- Prefer secret references or process environment injection.
- Treat source-preview keys as unstable until release evidence catches up.
# inspect public schema in the reference
# then edit only the intended user or project config scope