Aide-mémoire Grok Build

1. Install

macOS, Linux, and WSL:

curl -fsSL https://x.ai/cli/install.sh | bash

Windows PowerShell:

irm https://x.ai/cli/install.ps1 | iex

2. Launch

cd your-project
grok

Launch in a specific working directory:

grok --cwd /path/to/project

Use an API key:

export XAI_API_KEY="xai-..."
grok

3. Sign in and sign out

grok login
grok login --device-auth
grok logout

--device-auth is intended for SSH sessions, servers, containers, WSL, and other environments where opening a browser is inconvenient. (SpaceXAI Docs)

These are the top-level commands currently listed by the official CLI Reference. (SpaceXAI Docs)

grok inspect

Show exactly what Grok discovers in the current directory:

grok inspect
grok inspect --json

The report normally includes configuration sources, AGENTS.md and CLAUDE.md files, Skills, plugins, Hooks, MCP servers, Claude/Cursor/Codex-compatible configuration, authentication, and model settings. This is the most important command when a Skill, MCP server, Hook, or rule is not taking effect.

grok models

grok models

Lists models accessible through the current account, API key, or custom model endpoint.

Choose a model at launch:

grok -m <model-id>
grok --model <model-id>

Switch models in the interactive interface:

/model <model-id>
/m <model-id>

Version, completions, and managed setup

grok version
grok completions bash
grok completions zsh
grok completions fish
grok setup

grok setup primarily fetches and installs organization-managed Grok Build configuration. (SpaceXAI Docs)

One-shot execution

grok -p "Explain this repository"
grok --single "Explain this repository"

-p and --single run one task and then exit, which is useful for scripts, CI, bots, and automation. ([SpaceXAI Docs][4])

Output formats

grok -p "List all TODO comments" --output-format plain
grok -p "List all TODO comments" --output-format json
grok -p "Explain the architecture" --output-format streaming-json

JSON Schema output

grok -p "Analyze this project" \
  --json-schema '{"type":"object","properties":{"language":{"type":"string"}},"required":["language"]}'

--json-schema requires Headless mode to return JSON matching the supplied schema instead of free-form text. ([SpaceXAI][1])

CI and ACP

grok --no-auto-update -p "Run the test suite"

grok \
  --no-auto-update \
  --always-approve \
  --output-format json \
  -p "Review this pull request"

grok agent stdio

ACP mode communicates over stdin/stdout using JSON-RPC and is designed for IDEs, editors, and other agent clients. (SpaceXAI Docs)

Session and directory options

--session-id names a new session; it does not resume an existing one. Use --resume for that. ([SpaceXAI Docs][3])

Model and reasoning options

Available effort levels vary by model. Check with grok models or /effort. --reasoning-effort has been equivalent to --effort since v0.2.89. ([SpaceXAI][1])

Permissions

Headless permission modes:

grok -p "Review the API changes" \
  --permission-mode dontAsk \
  --allow 'Bash(git *)' \
  --allow 'Bash(gh *)' \
  --allow 'Read' \
  --allow 'Grep' \
  --deny 'Bash(rm -rf *)'

Permission filters include Bash, Edit, Read, Grep, MCPTool, and WebFetch:

--allow 'Bash(git *)'
--allow 'Edit(**/*.ts)'
--allow 'MCPTool(linear__*)'
--deny 'Edit(**/.env)'

Deny rules take precedence over allow rules. ([SpaceXAI Docs][5])

Sandbox profiles

grok --sandbox off
grok --sandbox workspace
grok --sandbox read-only
grok --sandbox strict
grok --sandbox my-custom-profile

The sandbox is applied when the process starts and cannot be fully removed in the middle of that process. ([SpaceXAI Docs][5])

Prompt and tool options

grok \
  --rules "Do not modify generated files. Run tests after every change." \
  -p "Refactor the authentication module"

Feature switches

--hunk-tracker-mode is a low-level, versioned option; use local grok --help for its current values. (SpaceXAI Docs)

Interface options

The --minimal and --fullscreen preference is remembered for future launches. (SpaceXAI)

Resume or continue work:

grok --resume <session-id>
grok --resume
grok -c

List, search, and delete sessions:

grok sessions list
grok sessions search "authentication"
grok sessions delete <session-id>

Export a session to stdout, a file, or the clipboard:

grok export <session-id>
grok export <session-id> output.md
grok export <session-id> --clipboard

Import Claude Code sessions:

grok import
grok import <target>
grok import <target1> <target2>

Capture a new session ID and continue it later:

SESSION_ID=$(
  grok -p "Start the refactor" \
    --output-format json |
  jq -r '.sessionId'
)

grok -r "$SESSION_ID" -p "Continue and run tests"

(SpaceXAI Docs)

Start a Worktree session

grok -w
grok --worktree
grok --worktree=feat "Refactor module X"
grok -w --ref main "Fix the flaky test"
grok -w -r <session-id>

In grok --worktree=feat "Refactor module X", feat is the Worktree name. With grok --worktree feat, some parsers may treat feat as the prompt, so the explicit equals-sign form is recommended.

Manage Worktrees

grok worktree list
grok worktree ls
grok worktree show <id>
grok worktree rm <id>
grok worktree rm <id1> <id2>
grok worktree rm <id> --dry-run
grok worktree gc
grok worktree gc --max-age 7d

(SpaceXAI Docs)

List servers

grok mcp list
grok mcp list --json

Add a local stdio server

grok mcp add filesystem -- \
  npx -y @modelcontextprotocol/server-filesystem /path/to/dir

Everything after -- is the real MCP server launch command.

Add a remote HTTP server

grok mcp add \
  --transport http \
  linear \
  https://mcp.linear.app/mcp

Add headers

grok mcp add \
  --transport http \
  api \
  https://mcp.example.com/mcp \
  --header "Authorization: Bearer ${API_TOKEN}"

grok mcp add \
  --transport http \
  example \
  https://example.com/mcp \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Team-ID: ${TEAM_ID}"

Headers may be repeated.

Project-scoped MCP

grok mcp add \
  --scope project \
  filesystem -- \
  npx -y @modelcontextprotocol/server-filesystem .

This writes .grok/config.toml in the project rather than user-global configuration.

Remove and diagnose

grok mcp remove <name>
grok mcp doctor
grok mcp doctor <name>
grok mcp doctor --json
grok mcp doctor <name> --json

Related options include -e for environment variables, -H / --header, --transport, and --scope project. (SpaceXAI Docs)

Plugin commands

grok plugin list
grok plugin install ...
grok plugin uninstall ...
grok plugin update ...
grok plugin enable ...
grok plugin disable ...
grok plugin details ...
grok plugin validate ...

Marketplace commands

grok plugin marketplace list
grok plugin marketplace add ...
grok plugin marketplace remove ...
grok plugin marketplace update ...

A Marketplace source may be a configured remote source or a local directory. Accepted arguments vary by source, so verify them with:

grok plugin install --help
grok plugin marketplace add --help

Plugins can contribute Skills, Agents, Hooks, MCP servers, LSP servers, and slash commands. (SpaceXAI Docs)

grok update
grok update --check
grok update --version <VERSION>
grok update --alpha
grok update --stable

Example:

grok update --check
grok update --version 0.2.101
grok update --alpha
grok update --stable

(SpaceXAI Docs)

grok wrap <command...>

Common forms:

grok wrap ssh user@host
grok wrap docker exec -it container bash
grok wrap kubectl exec -it pod-name -- bash

grok wrap runs the target command in a local PTY, receives OSC 52 clipboard content emitted by the remote process, and forwards it to the local clipboard. It is useful when running Grok through SSH, inside Docker containers, in Kubernetes Pods, or whenever remote copy operations cannot reach the local clipboard. The feature is currently marked experimental. (SpaceXAI Docs)

Type these commands after entering the interactive grok interface.

1. Help and navigation

/docs was added in v0.2.87 and may be absent from older Modes pages. ([SpaceXAI Docs][10])

2. Sessions

Newer versions open the Agent Dashboard directly from /sessions instead of showing only a simple history picker. ([SpaceXAI Docs][10])

3. Context and history

/compact Preserve the API design decisions and unresolved bugs
/copy
/copy 2

/history is a newer prompt-history search command. ([SpaceXAI Docs][10])

4. Models and reasoning

5. Permissions and work modes

Run /auto or /always-approve again to turn the mode off. /goal may depend on the account or a feature flag. /code-review has shipped as a built-in command since v0.2.51. ([SpaceXAI][1])

6. Side questions

/btw <question>
/btw Why did you choose Redis instead of PostgreSQL?

This asks a side question while minimizing disruption to the main task.

7. Background tasks and queue

/loop 5m Check whether the test suite passes and report failures
/loop 1h Check deployment health
/loop 1d Review new dependency updates

Intervals use Ns, Nm, Nh, or Nd. Seconds have a minimum of 60. Loops can run for at most seven days, with up to 50 scheduled tasks at once. ([SpaceXAI Docs][11])

8. Image and video generation

/imagine <prompt>
/imagine-video <prompt>

/imagine A clean isometric diagram of this system architecture
/imagine-video Animate this product mockup into a short presentation

Availability depends on the account, model, and media-generation access. ([SpaceXAI Docs][10])

9. UI and display

Built-in themes:

groknight
dark
grokday
light
day
tokyonight
tokyo
rosepine
rose-pine-moon
oscura
oscura-midnight
auto
system

([SpaceXAI Docs][10])

10. Terminal diagnostics

/terminal-setup
/terminal-check
/terminal-info

These equivalent commands check terminal type, True Color, clipboard transport, OSC 52, tmux/SSH state, Fullscreen support, and likely compatibility problems. ([SpaceXAI Docs][9])

11. Plugins, Skills, Hooks, and MCP

All six commands open the same Extensions panel with a different default tab.

Inside /mcps:

Project Hooks in .grok/hooks/ require /hooks-trust first. ([SpaceXAI Docs][12])

12. Memory

/memory, /mem, /flush, and /dream appear only when cross-session memory is enabled.

grok memory clear --workspace
grok memory clear --global
grok memory clear --all

(SpaceXAI Docs)

13. Account, usage, and privacy

/usage and /cost depend on account type and may be hidden for free accounts, some X plans, or API-key sessions. (SpaceXAI Docs)

14. Import, feedback, and release information

Every Skill marked as user-invocable automatically becomes a slash command:

/<skill-name>

/commit
/deploy
/review-pr
/generate-tests

If multiple sources provide the same Skill name, use a namespace:

/local:commit
/plugin-name:deploy

Skills may come from:

./.grok/skills/
~/.grok/skills/
plugin skills/ directories
~/.agents/skills/
~/.agents/commands/
Claude Code plugins and Skills

The local slash-command list can therefore be larger than the fixed commands documented here. (SpaceXAI Docs)

Prefix a prompt with ! to execute a Shell command directly:

!git status
!pnpm test
!npm run build
!docker compose ps

This runs the command directly rather than interpreting it as a natural-language task. Long-running commands may move to the background and remain visible through /tasks. (SpaceXAI)

Use @ in a prompt to reference files or directories:

@src/main.ts Explain this file
@package.json Check for outdated dependencies
@src/auth/ Refactor this module

This is input syntax rather than a separate slash command, but it is one of the most frequently used Grok Build features. (SpaceXAI Docs)

Changelogs have previously mentioned commands or internal options that the current official Reference no longer lists:

/execute-plan
grok agent --leader

/execute-plan existed in at least some May 2026 releases. It may have been replaced by Plan mode, /view-plan, and the normal execution flow, or may remain enabled only in some environments. Do not use historical commands in stable automation unless local /help confirms they are still available. (SpaceXAI)

Analyze an unfamiliar repository safely

grok \
  --sandbox read-only \
  --permission-mode dontAsk \
  -p "Analyze the architecture and identify security risks"

Modify code and run tests automatically

grok \
  --sandbox workspace \
  --always-approve \
  -p "Fix the failing tests, run the test suite, and summarize the changes"

CI code review

grok \
  --no-auto-update \
  --sandbox read-only \
  --permission-mode dontAsk \
  --allow 'Read' \
  --allow 'Grep' \
  --allow 'Bash(git *)' \
  --output-format json \
  -p "Review the current diff and return actionable findings"

Parallel feature development

grok \
  --worktree=feature-auth \
  --ref main \
  "Implement OAuth login and add tests"

Structured output

grok \
  -p "Audit this repository" \
  --output-format json \
  --json-schema '{
    "type": "object",
    "properties": {
      "summary": {"type": "string"},
      "risks": {
        "type": "array",
        "items": {"type": "string"}
      }
    },
    "required": ["summary", "risks"]
  }'

Allow only Git and GitHub CLI

grok \
  --permission-mode dontAsk \
  --allow 'Read' \
  --allow 'Grep' \
  --allow 'Bash(git *)' \
  --allow 'Bash(gh *)' \
  --deny 'Bash(*)' \
  -p "Review the open pull request"

Summary

The current command surface consists of roughly 20 top-level CLI commands, more than 40 fixed slash commands, over a dozen recent changelog additions, dynamically generated plugin and Skill commands, and the Headless, permission, Sandbox, Worktree, and structured-output options described above.

The most reliable local inventory is:

grok version
grok --help
grok mcp --help
grok plugin --help
grok sessions --help
grok worktree --help

Inside the TUI, run:

/help
/docs

Grok Build changes frequently, so check weekly for new commands, altered flags, and deprecations.