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

> xAI ships its coding agent as Grok Build, and an unaffiliated community grok-cli also exists. Install, auth, models, sandboxing and worktrees, checked September 2026.

- **Category:** Workflows
- **Updated:** 2026-09-22
- **Reading time:** 7 min
- **Canonical page:** https://cmdbrief.com/guides/grok-cli

## 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](https://github.com/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/`.

|  | Grok Build (xAI) | grok-cli (community) |
| --- | --- | --- |
| Repository | `xai-org/grok-build` | `superagent-ai/grok-cli` |
| Package | Install script only; no GitHub Releases published | `grok-dev` on npm, or an install script |
| Licence and stars | Apache-2.0, 27,014 stars | MIT, 3,481 stars |
| Latest activity | Monorepo sync 19 September 2026; stable channel pointer moved 21 September 2026 to `1.0.40` | `1.1.7` published 15 May 2026; last commit the same day |
| Auth variables | `XAI_API_KEY`, base URL override `GROK_XAI_API_BASE_URL` | `GROK_API_KEY`, `GROK_BASE_URL` |
| Config | `~/.grok/config.toml`, project `.grok/config.toml` | `~/.grok/user-settings.json`, `.grok/settings.json` |

*Read from both repositories, the GitHub API, the npm registry and the xAI docs on 22 September 2026. The community project is stale rather than abandoned: roughly four months without a commit or a release, and it is not archived.*

> **Tip:** Which one you have matters for tooling as well as support. CmdBrief targets the official xAI binary, because that is what writes `~/.grok/sessions/`, `~/.grok/logs/unified.jsonl` and `~/.grok/hooks/`. If `grok --version` prints a `1.x` build and `grok inspect` works, you are on Grok Build.

## Install and platforms

**Install Grok Build**

```bash
# 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](https://cmdbrief.com/guides/agent-cli-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.

**Headless and API-key auth**

```bash
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"
```

> **Warning:** Two money questions have no published answer. At announcement, Grok Build was “available now to all SuperGrok and X Premium Plus subscribers”, and xAI’s consumer docs say paid SuperGrok plans “raise your limits and unlock more across every product, drawing from a single weekly usage allowance” — but the xAI pricing pages return HTTP 403 to every fetch, no page publishes the size of that weekly allowance, and no page states whether an `XAI_API_KEY` alone is enough to run the CLI without a subscription. Confirm both in your own account before you plan around them.

## Models and context windows

| Model | Context window (tokens) | Notes |
| --- | --- | --- |
| `grok-build-0.1` | 256,000 | The coding model. Aliases `grok-code-fast-1`, `grok-code-fast`, `grok-code-fast-1-0825`. |
| `grok-4.7`, `grok-4.6`, `grok-4.5` | 500,000 | General frontier models. |
| `grok-4.3`, `grok-4.20-*` | 1,000,000 | Long-context line. |

*xAI model and pricing documentation, read 22 September 2026. Prompts of 200,000 tokens or more bill at twice the standard rate. Which model the CLI selects by default is not stated anywhere in the documentation.*

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

| Capability | Grok Build | Detail from the documentation |
| --- | --- | --- |
| MCP | Yes | `grok mcp list\|add\|remove\|doctor`. Project `.grok/config.toml` contributes `[mcp_servers]`. |
| Hooks | Yes | Lifecycle hooks on tool and session events. |
| OS sandbox | Yes | Landlock on Linux, Seatbelt on macOS. Off by default. Profiles `off`, `workspace`, `devbox`, `read-only` and `strict`, set with `grok --sandbox workspace`, a `[sandbox]` `profile` key, or `GROK_SANDBOX=`. |
| Permissions | Yes | `--allow <RULE>` and `--deny <RULE>`, evaluated separately from the sandbox. |
| Subagents | Yes, on by default | Built-ins `general-purpose`, `explore` and `plan`; custom agents in `.grok/agents/` or `~/.grok/agents/`; disable with `--no-subagents`. |
| Git worktrees | Yes, first class | `grok -w`, `--worktree=<name>`, `--ref <REF>`, and `grok worktree list\|show\|rm\|gc`. Worktrees land in `~/.grok/worktrees/<repo>/<name>`. In session, `/fork --worktree` and `Ctrl+W`. |
| Headless and ACP | Yes | `grok -p "…"` with `--output-format streaming-json`, plus full Agent Client Protocol support for other apps. |
| Open source | Yes | Apache-2.0, synced from an internal monorepo; external contributions are not accepted. |

*Read from the Grok Build documentation on 22 September 2026.*

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](https://cmdbrief.com/guides/run-claude-code-and-codex-in-parallel) 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](https://cmdbrief.com/guides/claude-code-sandbox) 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](https://cmdbrief.com/guides/kimi-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

**Session flags**

```bash
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](https://cmdbrief.com/guides/agent-cli-comparison) has all six side by side, [Claude Code vs Codex](https://cmdbrief.com/guides/claude-code-vs-codex) covers the two most people start from, and [the tool comparisons](https://cmdbrief.com/compare) cover the workspaces you would run them in.

## Questions

### Is Grok CLI the same as Grok Build?

Grok Build is xAI’s official coding agent, announced on 25 May 2026, and its binary is `grok` — so most people searching for “Grok CLI” want it. A separate, unaffiliated community project at `superagent-ai/grok-cli` also uses the name and publishes to npm as `grok-dev`; its README states it is not affiliated with, endorsed by or sponsored by xAI. The community project has had no commit or release since 15 May 2026.

### How do I install Grok Build?

Run `curl -fsSL https://x.ai/cli/install.sh | bash` on macOS or Linux, or `irm https://x.ai/cli/install.ps1 | iex` on Windows. Add `-s <version>` to the bash form to pin a build. `GROK_CHANNEL` selects `stable`, `alpha` or `enterprise`. The stable channel carried version 1.0.40 on 21 September 2026.

### Does Grok Build read CLAUDE.md?

Yes. It collects `AGENTS.md`, `Agents.md` and `AGENT.md` up to the repository root, and also reads `CLAUDE.md`, `Claude.md`, `CLAUDE.local.md` and `.claude/`. xAI’s documentation claims full compatibility with Claude Code with no configuration needed.

### Does Grok Build sandbox commands?

Yes, using Landlock on Linux and Seatbelt on macOS — but it is off by default. Profiles are `off`, `workspace`, `devbox`, `read-only` and `strict`, selected with `grok --sandbox workspace`, a `[sandbox]` profile key in configuration, or the `GROK_SANDBOX` environment variable. Permission rules via `--allow` and `--deny` are a separate layer.

### What does Grok Build cost?

xAI does not publish a price on a page that can be fetched — `x.ai/pricing` and `x.ai/build` both answer HTTP 403. At announcement it was available to SuperGrok and X Premium Plus subscribers, and xAI describes a single weekly usage allowance shared across its products without stating its size. API access is billed per token, with prompts of 200,000 tokens or more charged at double rate.

## Primary sources

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

- [Grok Build overview](https://docs.x.ai/build/overview)
- [Grok Build CLI reference](https://docs.x.ai/build/cli/reference)
- [Grok Build: sandbox](https://docs.x.ai/build/features/sandbox)
- [Grok Build: worktrees](https://docs.x.ai/build/features/worktrees)
- [Grok Build: subagents](https://docs.x.ai/build/features/subagents)
- [Grok Build: hooks](https://docs.x.ai/build/features/hooks)
- [Grok Build: MCP servers](https://docs.x.ai/build/features/mcp-servers)
- [Grok Build: skills, plugins and marketplaces](https://docs.x.ai/build/features/skills-plugins-marketplaces)
- [Grok Build: settings reference](https://docs.x.ai/build/settings/reference)
- [Grok Build: headless scripting](https://docs.x.ai/build/cli/headless-scripting)
- [xAI model and API pricing](https://docs.x.ai/developers/pricing)
- [xAI: announcing the Grok Build CLI](https://x.ai/news/grok-build-cli)
- [xai-org/grok-build repository](https://github.com/xai-org/grok-build)
- [superagent-ai/grok-cli (community project)](https://github.com/superagent-ai/grok-cli)

## Keep reading

- Comparisons: [Agent CLI comparison (2026): six terminal coding agents](https://cmdbrief.com/guides/agent-cli-comparison)
- Workflows: [Kimi CLI is now Kimi Code CLI: the 2026 guide](https://cmdbrief.com/guides/kimi-cli)
- Workflows: [Cursor CLI (2026): the agent binary, worktrees, hooks and quota](https://cmdbrief.com/guides/cursor-cli)

---

Markdown mirror of https://cmdbrief.com/guides/grok-cli, generated at build time from the same data the HTML page renders. Machine-readable index: https://cmdbrief.com/llms.txt