Grok Build CLI Cheatsheet: Commands, Shortcuts, Config, and Workflows

Grok Build CLI is SpaceXAI’s terminal coding agent. It can inspect a repository, edit files, run commands, search the web, delegate work to subagents, and run non-interactively in scripts or CI.

Its controls are spread across CLI flags, slash commands, keyboard shortcuts, and project files. This Grok Build cheat sheet puts the main commands in one place and includes working examples for worktrees, automation, extensions, and safety settings.

Read More: Grok Build: SpaceXAI’s Open-source Terminal AI Coding Agent

Last audited: September 10, 2026

This reference was checked against Grok Build v1.0.25. Run grok --help, grok <command> --help, or /release-notes after an update because commands can change between versions.

Grok Build essentials

Install and start Grok Build

On Windows, the installer places the binary in %USERPROFILE%\.grok\bin. Open a new PowerShell tab after installation, then confirm that the shell can find Grok Build:

grok --version
grok update

Open a terminal in your project directory and start the interactive interface:

cd your-project
grok

The first launch opens a browser for sign-in. Grok Build stores the resulting credentials in ~/.grok/auth.json. On a remote machine or another system without a browser, use device authentication:

grok login --device-auth

CI jobs can authenticate with an API key. Keep the key in your CI secret store:

# macOS, Linux, or WSL
export XAI_API_KEY="xai-..."
# PowerShell
$env:XAI_API_KEY="xai-..."

CLI commands and launch options

Shell commands start with grok and run outside the interactive TUI. You can use grok <command> --help to list the available options for a subcommand.

Common launch flags

Slash commands

Type / in the Grok Build prompt to open the command menu. The menu also lists installed user-invocable Skills. Built-in commands take priority when a Skill has the same name.

Sessions and context

Models, modes, and input

Extensions, agents, and scheduled work

Account, diagnostics, and help

Memory commands such as /memory, /flush, and /dream require experimental memory to be enabled. /remember is available without that flag and saves a direct note.

Keyboard shortcuts

Bindings can change with the focused pane and terminal. Open the live shortcut panel with Ctrl+.. Use Ctrl+X when your terminal cannot deliver that key combination.

Scrollback navigation

Vim scrollback mode replaces the arrow-first navigation with j, k, h, l, g, and G. Enable it with /vim-mode or set vim_mode = true under [ui].

While a turn is running, plain Enter queues a follow-up. On most terminals, Ctrl+Enter or Ctrl+I interjects so Grok Build handles the new instruction immediately. VS Code, Cursor, Windsurf, and Zed use Ctrl+L for that action.

Prompt syntax and mid-turn control

Type @ in a prompt to search for a file or directory. Grok Build respects .gitignore in this picker and hides dotfiles by default.

@src/main.rs Explain this file.
@src/main.rs:10-50 Review these lines.
@src/ Find the authentication flow in this directory.
@!.github Explain the CI workflows.

The ! after @ includes hidden files in the search. Attaching .env, private keys, or credential files can expose their contents to the active model. Inspect sensitive files yourself and pass only the lines the task requires.

Type ! on an empty prompt to enter shell mode. Use shell mode for a command you want to run yourself inside the TUI. When Grok Build runs a command as a tool, its permission and sandbox rules still apply.

Configuration and project rules

CLI flags win over environment variables, which win over ~/.grok/config.toml. The user config is the right place for defaults that should follow you across projects. Repository settings belong in .grok/ or AGENTS.md.

A practical user configuration

Start with a short config and add settings only after you know why you need them:

# ~/.grok/config.toml
[models]
default = "grok-build"
[ui]
vim_mode = false
show_thinking_blocks = true
remember_tool_approvals = true
[session]
auto_compact_threshold_percent = 85
[tools]
respect_gitignore = true

Run grok inspect after changing configuration. It shows the files and extension sources Grok Build discovered in the current directory, which is more reliable than guessing which layer won.

Project instructions with AGENTS.md

Put stable, actionable rules in AGENTS.md. Build commands, test commands, directory boundaries, and coding conventions belong there. General project history does not.

Grok Build reads instruction files from the repository root down to the current directory. Deeper files appear later in context and take precedence when rules conflict. It also reads recognized Claude instruction files for compatibility. Keep each file short because every loaded rule uses context.

# Project instructions
- Use TypeScript for new source files.
- Run `npm test` and `npm run lint` before finishing.
- Keep database queries in `src/repositories/`.
- Do not edit generated files under `dist/`.

Custom models

Custom models use OpenAI-compatible or supported provider endpoints. Store the key in an environment variable:

[model.my-model]
model = "model-id"
base_url = "https://api.example.com/v1"
name = "My Model"
env_key = "MY_MODEL_API_KEY"
context_window = 128000
[models]
default = "my-model"

Check the result with grok models, select it in the TUI with /model my-model, or use it for one run with grok -m my-model.

MCP, Skills, Plugins, and Hooks

Add and check MCP servers

# List servers
grok mcp list
# Add a local stdio server
grok mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir
# Add a project-scoped server
grok mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir
# Add a remote HTTP server
grok mcp add --transport http sentry https://mcp.sentry.dev/mcp
# Diagnose all servers or one server
grok mcp doctor
grok mcp doctor filesystem
# Remove a server
grok mcp remove filesystem

User-scoped MCP definitions go into ~/.grok/config.toml. The --scope project option writes to .grok/config.toml. Do not commit tokens in headers or environment maps. Reference a secret through ${VAR} instead.

Create a Skill

A Skill is a folder with a SKILL.md file. Put personal Skills under ~/.grok/skills/ and team Skills under .grok/skills/.

---
name: review-pr
description: Review a pull request for correctness and regressions. Use when asked to review a PR.
argument-hint: PR number or branch
user-invocable: true
---
# Review a pull request
1. Read the diff and surrounding code.
2. Check tests and error paths.
3. Report only actionable findings with file paths.

Manage Plugins

Enabling a Plugin loads its instructions and agent definitions. Trust controls code execution: project Plugin Hooks, MCP servers, and LSP servers stay inactive until you trust that Plugin. Inspect the source before adding --trust.

Use Hooks carefully

Hooks can approve, reject, observe, or modify tool flows. A project Hook is code from the repository, not a harmless text preference. Review .grok/hooks/, Plugin Hooks, and compatible Claude or Cursor Hook files before trusting an unfamiliar project. Successful Hook runs stay silent; Grok Build shows status only when a Hook blocks or fails.

Plans, subagents, and background work

Plan Mode

Plan Mode is for changes where architecture or requirements remain unsettled. Enter it with /plan or cycle to Plan with Shift+Tab. Grok Build reads the project, writes a session plan.md, and presents the plan for approval before implementation.

Normal file-edit tools cannot change project files while Plan Mode is active. The plan file is the exception. Shell commands and write-capable subagents require separate care because the parent plan gate does not inspect shell redirection or impose itself on child sessions.

Subagents

Subagents have separate context windows and report back to the parent. They can run in the shared workspace or in an isolated git worktree. Use worktree isolation for independent editing tasks that might otherwise touch the same files.

Press Ctrl+B to see subagents and background commands in the tasks pane. Use /workflows to inspect active workflow runs, or /workflow to pause or stop a background run the agent launched.

Background commands and recurring checks

A /loop fires immediately and then repeats. The minimum interval is 60 seconds, recurring jobs expire after seven days, and one session can keep up to 50 scheduled tasks. Scheduled tasks remind the agent to check results and finish, remove, or update the schedule. Use a background command for a dev server or one long test run. Use /loop for periodic checks. Use monitor only when each selected output line deserves a notification.

Headless mode and scripting

Headless mode sends one prompt, lets the agent use its available tools, prints the result, and exits. A new session is created by default.

grok -p "Explain this codebase"

Structured output and session continuation

The final JSON object can include response text, stop reason, session ID, token use, model use, and cost fields when the server supplies complete data. Do not treat a missing cost field as zero cost.

# Capture the session ID
grok -p "Review the current diff" --output-format json
# Continue that exact session
grok -p "Now check the error paths" --resume <session-id>
# Continue the newest session in this directory
grok -p "Continue the task" -c
# Stream events for a bot or integration
grok -p "Run the tests and summarize failures" --output-format streaming-json

Limit a review to read-only tools

On PowerShell, put the command on one line or replace Bash line continuations with PowerShell backticks.

grok -p "Review this repository for correctness issues" \
  --tools "read_file,grep,list_dir" \
  --sandbox read-only \
  --output-format json

Permissions and sandboxing

Permissions decide whether a requested action is approved, denied, or shown for confirmation. The sandbox limits what the process can access after an action is approved. Use both layers for unfamiliar code.

For a predictable daily default, keep approval prompts enabled in ~/.grok/config.toml. Change the value to "always-approve" only in an environment where automatic tool approval is acceptable.

[ui]
permission_mode = "ask"

Compatibility permission modes

Grok Build also reads permissions.defaultMode from compatible .claude/settings.json files. That setting accepts the following modes:

For daily interactive work, keep the default prompt behavior and add narrow rules for commands you run often. Avoid a broad Bash allow rule.

# .grok/config.toml
[permission]
allow = [
  "Bash(git *)",
  "Bash(npm test*)",
  "Read(src/**)",
  "Grep",
]
deny = [
  "Bash(rm -rf *)",
  "Read(**/.env)",
  "Edit(**/.env)",
]

Deny rules take precedence over ask and allow rules, regardless of which config file contains them. Shell rules can be subtle around chained commands, wrappers, and wildcards. Pair narrow allows with explicit denials for destructive commands, then test representative cases before using the policy in automation.

Sandbox profiles

Sandboxing is off by default. Linux uses Landlock and related kernel controls; macOS uses Seatbelt. Network restrictions apply to child processes on Linux, but not to built-in web tools or the model connection. macOS sandbox profiles do not block child-process network access.

Block secrets with a custom profile

# .grok/sandbox.toml
[profiles.project]
extends = "workspace"
restrict_network = true
deny = ["**/.env", "**/*.pem", "**/*.key"]

grok --sandbox project

A non-empty deny list blocks reads and writes at the OS level. Linux expands deny globs against files that exist at launch. Use exact paths for secrets that must remain blocked even if files appear later. Grok Build refuses to start when an explicitly requested custom profile cannot be applied.

A session keeps the sandbox profile it started with. Resume will reject a different profile. Start a new session if you need a different access boundary.

Sessions, Rewind, and Memory

Grok Build saves each conversation automatically under ~/.grok/sessions/. A session includes messages, tool results, task state, token counters, file snapshots for Rewind, and child-session records.

Rewind restores file snapshots and truncates later conversation history. Git remains the safer long-term recovery mechanism because a Rewind discards the later state. Commit or stash work you may need again.

Cross-session Memory is experimental. Enable it with --experimental-memory, GROK_MEMORY=1, or the documented config setting before using /memory, /flush, and /dream. Review saved memories instead of assuming every old detail still applies.

Grok Build workflow examples

Understand an unfamiliar repository

grok --sandbox read-only "Map this repository. Explain the entry points, main modules, test setup, and the path a request follows through the application. Cite file paths."

The read-only sandbox protects project files while Grok Build explores. Follow with a narrower prompt about the module you plan to change.

Plan a feature before editing

/plan Add passwordless email login. Reuse the current session middleware and identify the database, route, UI, and test changes.

Read the proposed file paths and verification steps before pressing a. Press s and send corrections when the plan ignores an existing utility or chooses the wrong boundary.

Fix a failing test

Run the failing auth tests. Find the first real failure, explain the cause, make the smallest justified fix, then rerun the focused tests and the related suite.

Ask for the cause before authorizing a change, then require both the focused test and the full suite. A single passing test is not enough to verify the fix.

Review the current diff without changing files

grok -p "Review the current git diff for correctness, regressions, missing tests, and unsafe error handling. Report only actionable findings with file paths and line numbers." --tools "read_file,grep,list_dir,run_terminal_cmd" --deny "Bash(git push*)" --sandbox read-only

The read-only sandbox blocks project edits. The explicit push denial adds another boundary around the shell tool.

Refactor in an isolated worktree

grok --worktree=auth-cleanup --ref main "Refactor the authentication middleware to remove duplication. Preserve behavior, add focused tests, and show the final diff."

The named worktree keeps the refactor separate from your main checkout. Review and merge its changes only after the tests and diff look right.

Keep a long session focused

/context
/compact preserve the accepted API contract, changed file list, open test failure, and remaining tasks

Check context before compacting. A specific compact instruction protects decisions that a generic summary might omit.

Add a project MCP server

grok mcp add --scope project --transport http sentry https://mcp.sentry.dev/mcp
grok mcp doctor sentry
grok inspect

The project scope makes the server discoverable from the repository config. Review the file before committing it, especially headers and environment values.

Delegate repository research

Use an explore subagent to trace every caller of the payment retry function. Return the call paths, tests that cover them, and any inconsistent retry limits. Do not edit files.

An explore subagent can search and run inspection commands without editing. The parent keeps its context for the main task and receives a summary when research finishes.

Run a dev server in the background

Start `npm run dev` in the background. Wait for the ready message, then implement the login form and verify it against the running app.

Press Ctrl+B to inspect the server task. Ask Grok Build to stop it when verification ends so the process does not keep the port open.

Watch a CI run

/loop 2m Check the GitHub Actions run for this branch. Report only when its status changes or when it finishes.

The instruction limits repeated noise. Delete the scheduled task after the run completes if Grok Build does not remove it as part of the task.

Run an unattended formatting task

grok -p "Format the changed source files, run the formatter check, and report the files changed." --always-approve --sandbox workspace --deny "Bash(git push*)" --deny "Bash(rm -rf *)"

Always-approve removes interactive prompts. Run unattended edits only in a clean checkout where you can inspect or discard the diff.

Move from Claude Code without copying assumptions

/import-claude
# Then check what Grok Build loaded
grok inspect

The import can bring over supported permissions, environment variables, MCP servers, Hooks, and paths. Inspect the result because compatibility does not mean every Claude Code command or behavior has a Grok Build equivalent.

Troubleshooting

FAQs

What is Grok Build?

Grok Build is SpaceXAI’s terminal-based AI coding agent. It has an interactive TUI, a headless mode for scripts and CI, and an ACP mode for compatible editors and clients. It can inspect code, edit files, execute commands, search the web, and coordinate longer tasks.

Is Grok Build the same as Grok on the web?

No. Grok Build is the coding agent and CLI that runs from a terminal or integration client. Grok on the web is the general chat product. Their accounts and models are related, but their commands and interfaces are different.

Does Grok Build work on Windows?

Yes. The official PowerShell installer provides a native Windows binary. Git Bash and WSL are also supported installation paths. Some keyboard combinations differ in Windows Terminal and editor-integrated terminals. Use /terminal-setup when a shortcut does not work.

Do I need an xAI API key?

Not for the normal browser sign-in flow. An API key is the practical choice for CI, containers, and other environments where interactive account login is unavailable. Device authentication is another option for a remote machine.

Where does Grok Build store its configuration?

User configuration lives under ~/.grok/, or %USERPROFILE%\.grok\ on Windows. The main files are config.toml and pager.toml. Project extensions and rules can live under .grok/ in the repository.

Does Grok Build support AGENTS.md?

Yes. Grok Build loads project instruction files from the repository root to the current directory. Deeper instructions take precedence when files conflict. It also supports several Claude instruction filenames for compatibility.

How do I run Grok Build without the TUI?

Use grok -p "Your prompt". Add --output-format json for one machine-readable result or --output-format streaming-json for a live event stream. Headless runs create fresh sessions unless you resume or continue one.

What is the difference between Plan Mode and an explore subagent?

Plan Mode prepares an implementation plan for the current session and waits for approval before normal edit tools can change project files. An explore subagent investigates a bounded question in a separate context and returns a summary. Use Plan Mode for a change that needs your approval. Use an explore subagent for parallel research.

Does Always-approve disable every safety control?

No. Always-approve removes normal confirmation prompts, but explicit deny rules, ask rules, restrictive Hooks, and the OS sandbox can still block actions. It still deserves care because any action without one of those restrictions can proceed automatically.

Can Grok Build use Claude Code Skills and settings?

Grok Build includes compatibility for several Claude Code rule, Skill, command, MCP, Hook, and session locations. It also provides /import-claude. You can use grok inspect to confirm what loaded and do not assume a Claude slash command exists in Grok Build.

How is Grok Build different from Codex CLI and Claude Code?

All three are coding agents that can inspect repositories, edit files, and run commands. Grok Build has its own TUI, models, permission system, sandbox profiles, slash commands, extension discovery, session storage, subagents, and ACP interface. Use the cheatsheet for the tool you are running instead of carrying commands across products.

Related resources

• Grok Build documentation: Official setup, modes, features, settings, and CLI pages.
• Grok Build on GitHub: Source code, installation commands, repository notes, and license.
• Grok Build user guide: Detailed reference for configuration, extensions, sessions, sandboxing, and advanced use.
• Claude Code Commands Cheat Sheet: Claude Code slash commands, CLI options, permissions, Skills, Plugins, agents, and workflows.
• OpenAI Codex Commands Cheat Sheet: Codex CLI commands, flags, configuration, MCP, sandbox settings, and practical workflows.
• Antigravity CLI Cheatsheet: Commands, Setup, Shortcuts, and Workflows.
• GitHub Copilot Cheat Sheet: CLI & Slash Commands, Variables, and Shortcuts