Jul 28, 2026

Grok Build CLI: Install, Commands, and config.toml (the Practical Handbook)

Read time: ~8 minutes. TL;DR — install and run:
curl -fsSL https://x.ai/cli/install.sh | bash   # macOS / Linux / Git Bash
grok --version                                  # verify
grok                                            # launch the TUI
Config lives at ~/.grok/config.toml. Headless (CI): grok -p "your prompt" --output-format json.

Sourcing note: every command, flag, and config key below is quoted from xAI’s official user guide shipped inside the open-source xai-org/grok-build repo (crates/codegen/xai-grok-pager/docs/user-guide/, 24 chapters). Where the official docs don’t specify something (e.g. editor-side ACP setup), this guide says so rather than inventing steps. Links at the bottom.

If you’ve installed Grok Build (xAI’s terminal coding agent) and now want the actual manual — how to pin a version, what the slash commands do, where settings live, how to run it in CI — this is that page. The overview guide covers what Grok Build is; this one is the handbook.

1. Install (including a specific version)

macOS / Linux / Git Bash:

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

Pin a specific version (the flag most install guides miss):

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

Windows (PowerShell) — a native installer, which also adds %USERPROFILE%\.grok\bin to your User PATH:

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

# specific version
$env:GROK_VERSION="0.1.42"; irm https://x.ai/cli/install.ps1 | iex

WSL users get the Linux binary automatically; Git Bash / MSYS2 users can use the bash script.

Verify, then update:

grok --version
grok update      # update to latest at any time

Note on curl … | bash: it executes whatever the URL returns. It’s what xAI documents, but if you’re security-conscious, download install.sh, read it, then run it.

2. Launch and authenticate

grok

On first launch Grok opens your browser to authenticate against your xAI account. After that, grok in any project directory drops you into the full-screen TUI with your codebase in scope.

3. The slash commands that actually matter

Type / in the prompt to open a fuzzy-matching command menu. Commands come from two places — shell builtins (the agent backend, xai-grok-shell) and pager builtins (the TUI frontend, xai-grok-pager) — plus any enabled skill marked user-invocable: true.

The ones worth learning first:

Command	What it does
`/new` (alias `/clear`)	Start a fresh session, clear the conversation
`/resume`	Session picker — reload a previous session from disk
`/compact [note]`	Compress history to reclaim context. Pass a note to steer what’s kept
`/context`	Breakdown of context usage: system prompt, messages, reasoning/overhead, free space — plus estimated token cost of tool definitions, the skills listing, and MCP announcements
`/session-info` (aliases `/status`, `/info`)	Auth method, model, turn count, context usage
`/fork`	Branch the session into a new agent, keeping history to this point
`/rewind`	Roll back to an earlier turn, discarding everything after

Two practical notes:

/compact accepts an instruction, which most people never use:
```
/compact keep the auth implementation details
```
Grok auto-compacts at 85% context, and that threshold is tunable via [session] auto_compact_threshold_percent in config.

If you care about token cost (and on a long agent session you should), /context is the command to run — it itemizes what’s eating your window, including MCP servers you may have forgotten are attached. That’s the same diagnosis loop we walk through for Claude Code’s token overhead.

4. config.toml: where settings live

Location: ~/.grok/config.toml. If the file doesn’t exist, Grok uses built-in defaults — you only write the keys you want to override.

Settings precedence (highest wins)

CLI flags — e.g. --yolo, --model, --sandbox
Environment variables — e.g. XAI_API_KEY, GROK_MEMORY
~/.grok/config.toml
Managed / requirements config — files your org may deploy (managed_config.toml / requirements.toml)
Built-in defaults

That order matters in CI: a flag beats an env var beats your config file.

The keys worth knowing

[cli]
auto_update = true                # check for updates on launch

[models]
default = "grok-4.5"              # model for new sessions
web_search = "grok-4.5"           # model used by the web_search tool
temperature = 0.7
top_p = 0.95
max_completion_tokens = 8192
max_retries = 8
stream_tool_calls = true

[ui]
simple_mode = true                # readline-style prompt editing (default); false = vim editing
vim_mode = false                  # vim-style scrollback navigation (default: false)
show_thinking_blocks = true       # show agent thinking in the TUI (default: true)
collapsed_edit_blocks = false     # show edits as one-line +N/-M diffstat summaries (default: false)
screen_mode = "fullscreen"        # "fullscreen" | "minimal"
remember_tool_approvals = false   # per-command "Always allow" on permission prompts (default: false)

[features]
telemetry = false                 # anonymous usage telemetry
codebase_indexing = true          # code graph indexing (default: true)
lsp_tools = false                 # expose the lsp tool
remote_fetch = true               # online model-catalog fetches — set false for air-gapped setups

Three worth changing on day one:

[features] telemetry — set false if you don’t want anonymous usage data sent.
[features] remote_fetch — set false on firewalled/air-gapped machines so it stops trying online catalog fetches.
[ui] collapsed_edit_blocks = true — if the agent makes many edits, this folds them into +N/-M diffstat rows instead of full diffs.

(The full configuration chapter is ~42 KB and covers far more — per-model overrides, theming, permissions. Start with the keys above.)

5. Headless mode: Grok in scripts and CI

Passing a prompt non-interactively triggers headless mode. It runs the prompt with full tool access and prints the result to stdout, then exits.

grok -p "Summarize the failing tests and propose a fix"

Machine-readable output — the reason to use it in CI:

grok -p "List every TODO with file and line" --output-format json

--output-format accepts plain, json, or streaming-json.

The headless flags worth memorizing

Flag	Purpose
`-p, --single <PROMPT>`	The prompt (also `--prompt-json`, `--prompt-file`)
`-m, --model <MODEL>`	Model to use
`-c, --continue`	Continue the most recent session in this directory
`-r, --resume <ID_OR_TITLE>`	Resume a session (scripts should prefer IDs)
`--fork-session`	With `-r`/`-c`, fork into a new session instead of appending
`--cwd <PATH>`	Working directory
`--output-format <FMT>`	`plain` / `json` / `streaming-json`
`--max-turns <N>`	Cap agentic turns before stopping (headless only)
`--tools <TOOLS>`	Allowlist of built-in tools (headless only)
`--disallowed-tools <TOOLS>`	Denylist of built-in tools (headless only)
`--allow <RULE>` / `--deny <RULE>`	Permission rules with glob patterns (repeatable)
`--sandbox <PROFILE>`	Sandbox profile for filesystem/network access
`--reasoning-effort <LEVEL>`	`none`/`minimal`/`low`/`medium`/`high`/`xhigh`/`max`
`--yolo`	Auto-approve all tool executions

Two safety notes for CI:

--max-turns is your runaway guard. An agent loop with no turn cap can spin; set it.
--yolo auto-approves everything. Convenient in a disposable container, dangerous on a dev machine. Prefer --allow/--deny glob rules or a --sandbox profile for anything with real credentials.

A realistic CI invocation:

grok -p "Review the diff on this branch and list blocking issues" \
  --output-format json \
  --max-turns 20 \
  --sandbox strict

6. Editor integration (ACP) — what’s actually documented

Grok Build can be integrated into editors via the Agent Client Protocol (ACP) — that’s stated plainly in the official getting-started guide. What the user guide doesn’t publish is a step-by-step editor-side setup, so this guide won’t invent one. If you’re wiring an ACP-capable editor to it, follow your editor’s ACP client instructions and point it at the grok binary; check the repo docs for updates, since the guide ships in-tree and changes with releases.

7. What else ships in the manual

The official user guide has 24 chapters. Beyond what’s above, the ones most people want next:

07-mcp-servers — attaching MCP servers (mind the context cost; check with /context)
08-skills / 09-plugins / 10-hooks — extensibility
12-project-rules / 13-memory — per-project instructions and persistence
16-subagents / 19-plan-mode / 20-background-tasks — agentic workflow control
18-sandbox / 22-permissions-and-safety — read these before --yolo
24-monitoring-usage — usage tracking

They’re all in the repo at crates/codegen/xai-grok-pager/docs/user-guide/, and because Grok Build is Apache 2.0 open source, you can read the tool implementations alongside the docs.

The takeaway

The practical Grok Build loop: install (curl -fsSL https://x.ai/cli/install.sh | bash, or bash -s 0.1.42 to pin), grok update to stay current, grok to launch, and /context + /compact to keep long sessions from eating their own window. Settings live in ~/.grok/config.toml — flags beat env vars beat the file — and the keys worth touching first are telemetry, remote_fetch, and collapsed_edit_blocks. For CI, grok -p "…" --output-format json with --max-turns as a runaway guard and --allow/--deny or --sandbox instead of --yolo.

For what Grok Build is and how it compares, see How to Use Grok Build; for the same daily-driver mechanics in another agent, Claude Code as a daily driver. If you want an entirely local alternative using your own GGUF model, follow the safe llama-server built-in tools setup.

Sources

xai-org/grok-build — official user guide — 24 chapters shipped in-tree
01-getting-started.md — install (incl. bash -s <version>, PowerShell installer, %USERPROFILE%\.grok\bin PATH), grok --version, grok update, first-launch browser auth, ACP mention
04-slash-commands.md — /new (/clear), /resume, /compact [context], /context, /session-info (/status, /info), /fork, /rewind; shell vs pager builtins; auto-compact at 85% via [session] auto_compact_threshold_percent
05-configuration.md — ~/.grok/config.toml, precedence order (CLI flags → env vars → config.toml → managed config → defaults), [cli] / [models] / [ui] / [features] keys
14-headless-mode.md — -p/--single, --output-format plain|json|streaming-json, --max-turns, --tools/--disallowed-tools, --allow/--deny, --sandbox, --reasoning-effort, --yolo, session flags
Editor-side ACP setup is not published in the user guide — follow your editor’s ACP client docs. Commands verified against the repo on July 28, 2026; the guide syncs periodically from xAI’s monorepo, so confirm against the live repo.