Grok CLI is now Grok Build: install, models, limits

Grok CLI is now Grok Build — and there are two of them

xAI’s terminal coding agent was announced on 25 May 2026 as an early beta and is called Grok Build. The repository is xai-org/grok-build, the docs live under docs.x.ai/build, and the binary you type is grok. The docs describe it as “a powerful and extensible coding agent. Use it via an interactive TUI, headlessly in scripts or bots, or through the Agent Client Protocol (ACP) in other apps.” The repository description is blunter: “SpaceXAI’s coding agent harness and TUI. Fullscreen, mouse interactive, extensible.”

There is also an unaffiliated project that calls itself grok-cli, at superagent-ai/grok-cli, published to npm as grok-dev. Its own README says it “is community-built, open-source, and not affiliated with, endorsed by, or sponsored by xAI Corp.” The two are genuinely confusable, because both write into ~/.grok/.

Install and platforms

# macOS and Linux
curl -fsSL https://x.ai/cli/install.sh | bash

# Windows, PowerShell
irm https://x.ai/cli/install.ps1 | iex

# pin a specific build
curl -fsSL https://x.ai/cli/install.sh | bash -s 0.1.42

grok --version
grok inspect --json

The installer reads four environment variables worth knowing about: GROK_CHANNEL, which accepts stable, alpha or enterprise and defaults to stable; GROK_BIN_DIR for the install location; GROK_PROXY_URL; and GROK_DEPLOYMENT_KEY for managed deployments. The stable channel pointer carried 1.0.40 on 21 September 2026. There are no GitHub Releases to watch — the repository is synced from an internal monorepo and, in its own words, does not accept external contributions — so the channel pointer is the version feed.

macOS, Linux and Windows are all supported, with Windows builds described as best-effort. The installer’s own comment spells out the Windows path: run it under Git for Windows or MSYS2 Bash using the same curl | bash flow, while WSL uses the Linux binary. That is the same shape of caveat Kimi Code carries; the six-agent comparison lines up the platform support for all of them.

Auth: a subscription or an API key

First launch opens a browser login and writes a token to ~/.grok/auth.json. grok login re-runs it, and grok login --device-auth handles machines with no browser — a remote box, a CI runner, a container. The API-key fallback is an environment variable.

grok login --device-auth

export XAI_API_KEY="xai-..."
grok

# point the CLI at a different endpoint
export GROK_XAI_API_BASE_URL="https://api.x.ai/v1"

Models and context windows

List what your account can reach with grok models, pick one with -m / --model <MODEL> at launch or /model <name> in session. You can also register an arbitrary OpenAI-compatible endpoint as a [model.my-model] block in ~/.grok/config.toml, giving it a base_url and an env_key — which makes Grok Build one of the few first-party agent CLIs that will happily drive somebody else’s model.

What it supports: the most feature-complete of the newer agents

Worktrees deserve the emphasis. A one-flag worktree with garbage collection built in is exactly the mechanic that makes parallel agent work tolerable, and it is documented for Grok Build, Claude Code and Cursor CLI, while Codex documents it for the desktop app rather than the CLI. If running several agents at once is the point, the parallel worktree setup is the same pattern applied to a mixed stack.

The sandbox default is worth a second look before you trust it. Grok Build ships a real kernel-level sandbox on both Linux and macOS, and ships it switched off. Turning it on is one flag or three lines of TOML, and grok inspect will tell you which profile is live. The sandbox and permission guide covers how to match authority to consequence; the principle transfers even though the mechanism is xAI’s.

It reads both AGENTS.md and CLAUDE.md

This is the most useful under-reported fact about Grok Build. It walks up to the repository root collecting AGENTS.md, Agents.md and AGENT.md, and it also reads CLAUDE.md, Claude.md, CLAUDE.local.md and the .claude/ directory. The docs claim “full compatibility with Claude Code with zero configuration needed.” In practice that means you can point Grok Build at a repository that has only ever been driven by Claude Code and it will pick up the house rules without you writing anything new.

• Skills are discovered in ./.grok/skills/, ~/.grok/skills/, ~/.agents/skills/ and ~/.agents/commands/.
• Plugins are discovered in ./.grok/plugins/, ~/.grok/plugins/ and ~/.grok/plugins/marketplaces/, plus anything passed with --plugin-dir.
• User configuration is ~/.grok/config.toml; on Windows, %USERPROFILE%\.grok\config.toml.
• Project configuration is .grok/config.toml, and it contributes only [mcp_servers], [plugins] and [permission] — a deliberate limit on what a checked-out repository can change about your agent.
• Sandbox profiles live in ~/.grok/sandbox.toml or .grok/sandbox.toml.
• grok inspect [--json] prints everything it discovered: config, instructions, skills, plugins, hooks and MCP servers.

Contrast that with Kimi Code CLI, which reads AGENTS.md and nothing else, and with OpenCode v2, which dropped its CLAUDE.md fallback on purpose. If one repository has to serve several agents, the shared file is AGENTS.md; Grok Build simply also accepts the Claude-shaped ones.

Sessions and resume

grok -c                     # continue the last session
grok -r                     # pick a session to resume
grok -r <ID>                # resume a specific session
grok -s <UUID>              # start with a session id you choose
grok --fork-session         # branch rather than continue

grok -w -r <ID>             # resume into a fresh worktree
grok worktree list
grok worktree gc

Sessions are stored under GROK_HOME, which defaults to ~/.grok, with a summary.json per session. grok -w -r <id> is the combination worth remembering: it reopens an existing conversation in a brand-new worktree, so a second attempt at the same task cannot collide with the first one’s files.

Where CmdBrief fits

CmdBrief runs Claude Code, Codex, Grok CLI, Kimi CLI, OpenCode and Cursor CLI from one Mac workspace (Claude, Codex, Grok and Cursor can lead): per-product workspaces, working, needs-input and done states, diff review and an integrated terminal. For Grok it maintains a managed hook file in ~/.grok/hooks/ so the pane knows when the agent is waiting on you, and it reads sessions from ~/.grok/sessions/**/summary.json.

Usage is the part that needed work. Grok Build publishes no grok usage command and no API for the weekly allowance, so CmdBrief parses weekly credit consumption out of ~/.grok/logs/unified.jsonl — the CLI’s own billing log — and shows it beside the Claude Code and Codex windows. It is a derived figure from a local file, not a vendor endpoint, and that is worth knowing when you compare it against what xAI eventually bills you.

If you are deciding whether Grok Build earns a slot next to what you already run, the agent CLI comparison has all six side by side, Claude Code vs Codex covers the two most people start from, and the tool comparisons cover the workspaces you would run them in.

Primary sources

Provider terms and product behavior can change. Confirm plan, pricing, model, and permission details in the current official documentation.

• 01Grok Build overviewdocs.x.ai
• 02Grok Build CLI referencedocs.x.ai
• 03Grok Build: sandboxdocs.x.ai
• 04Grok Build: worktreesdocs.x.ai
• 05Grok Build: subagentsdocs.x.ai
• 06Grok Build: hooksdocs.x.ai
• 07Grok Build: MCP serversdocs.x.ai
• 08Grok Build: skills, plugins and marketplacesdocs.x.ai
• 09Grok Build: settings referencedocs.x.ai
• 10Grok Build: headless scriptingdocs.x.ai
• 11xAI model and API pricingdocs.x.ai
• 12xAI: announcing the Grok Build CLIx.ai
• 13xai-org/grok-build repositorygithub.com
• 14superagent-ai/grok-cli (community project)github.com