Grok CLI: install, commands, models, and how it works

What "Grok CLI" actually is

xAI does not sell a product called "Grok CLI." Its terminal coding agent is officially Grok Build, and the binary it installs is grok. The names blur because the whole category trained people to expect one: Anthropic ships Claude Code, OpenAI ships the Codex CLI, and "the CLI named after the model" carried straight over to Grok. This guide says Grok CLI in the title because that is what people type into a search bar, and Grok Build in the body because that is what xAI calls it.

Grok Build launched in early beta on 14 May 2026, gated to SuperGrok Heavy. It opened to all SuperGrok and X Premium+ subscribers on 25 May 2026, and Grok Build 1.0 shipped on 7 August 2026, ending the beta. No model changed at that release. 1.0 bought stability and a wider command surface, nothing more.

Install Grok CLI

There is no npm package and no Homebrew formula for the official CLI as of August 2026. xAI ships a single install script per platform.

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

grok --version

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

grok --version

The installer drops the binary on your PATH and registers a shell entry, so a fresh terminal window finds grok immediately. If it does not, restart your shell before you troubleshoot anything else. To update later, use the CLI's own updater rather than re-running the install script.

grok update --check
grok update

Authenticate it

The first time you launch grok in interactive mode, it opens a browser window to complete OAuth sign-in against your xAI or X account. That account needs to carry a subscription tier that includes Grok Build access, covered below.

grok
# opens a browser for sign-in on first launch

Two situations break that flow: a remote box with no browser, and a script or CI job that must never block waiting for a human to click something.

export XAI_API_KEY="your-key-here"
grok -p "list every TODO comment in this repository"

Models and reasoning effort

The default model is grok-4.5, xAI's flagship since its July 2026 release. Nothing locks the CLI to it. One command lists your account's full lineup, including any custom models you registered yourself.

grok models
grok -m <model-id> -p "your prompt"

Custom or self-hosted model endpoints can be registered in the CLI's own config file rather than passed on every command line.

[models.custom]
# add non-default model endpoints here; see `grok models --help`

Reasoning effort is a separate dial from model choice. The documented levels are none, minimal, low, medium, high, xhigh, and max, but only the ones your selected model advertises are accepted. A model that does not support a level rejects the run rather than silently rounding down to something cheaper.

grok --effort high -p "explain the retry logic in internal/queue"
grok -m <model-id> --effort xhigh

Grok CLI commands and flags

Subcommands

Flags

Interactive TUI vs headless mode

Running grok with no arguments opens a full-screen, mouse-interactive terminal UI: chat pane, plan view, inline tool approvals. That is the mode for sitting down and working a task through.

Headless mode is what makes the CLI callable from a script, a Makefile, or another agent's shell. It takes one prompt, runs whatever tools the task needs, prints the result, and exits with a status code you can branch on.

grok -p "Summarize what internal/queue does. Do not edit files." --cwd ~/code/your-project

grok -p "list every exported function with no doc comment" \
  --output-format json | jq

For CI or another agent that must parse the result reliably, pair headless mode with --json-schema rather than asking for JSON in plain English. A supplied schema is a contract; a sentence asking politely for JSON is not.

MCP servers

MCP works out of the box, covering both local stdio servers and remote HTTP servers with automatic OAuth.

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

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

# with a static auth header instead of OAuth
grok mcp add --transport http api https://mcp.example.com/mcp \
  --header "Authorization: Bearer ${API_TOKEN}"

You can also declare servers in config, which is the right move for a team setup checked into the repository with --scope project.

grok mcp list
grok mcp doctor          # diagnose a misbehaving server
grok mcp remove <name>

Inside the interactive TUI, /mcps opens the same management surface: toggle a server with space, refresh after a config edit, and authenticate an OAuth server without leaving the session.

Pricing and subscriptions

Installing Grok Build costs nothing. Running it is not free. You need either a qualifying xAI subscription or a separately billed API key, and those are two different rails that do not top each other up.

Grok CLI vs Claude Code, Codex CLI, and Gemini CLI

All four are terminal-native agents that read a repository, edit files, run shell commands, and speak MCP. In practice the differences that decide your choice are billing and ecosystem maturity, not raw model quality.

Against Claude Code: Anthropic's CLI has the longest track record in this category, the deepest plugin and skill ecosystem, and a permission model most teams have already tuned. Grok CLI's equivalents (plugins, hooks, MCP, worktree-scoped sessions) exist and cover similar ground, but they are newer, and less has been written about their edge cases. If your team is already deep in Claude Code's conventions, that familiarity is worth something Grok CLI cannot yet offer.

Against Codex CLI: OpenAI's tool and Grok Build both ship a headless mode built for scripting and both support structured JSON output, so the two feel closest in shape. The real choice usually comes down to which subscription you already pay for and which model answers your specific codebase better, which is worth testing directly rather than trusting a benchmark number. Anyone weighing Codex against Claude Code specifically has a dedicated Codex vs Claude Code comparison.

Against Gemini CLI: Google's tool went through its own naming shift in 2026 when Antigravity CLI took over serving individual accounts. Grok CLI has not gone through an equivalent access cutover: the same grok binary that launched in May 2026 is the one you install today, just further out of beta. If you were burned by Gemini CLI's auth rail changing under you, that stability is a point in Grok CLI's favor.

If you run more than one of these, one recent addition matters: Grok Build can resume a Claude Code session, importing its transcript so the conversation continues inside Grok. That is transcript portability, not a live handoff, and its limits are worth knowing before you lean on it mid-task. The mechanics are in resuming Claude Code sessions in Grok.

When it does not behave

Questions people ask

Keep reading