Install Grok CLI (Grok Build): Windows, macOS, Linux

Grok Build is SpaceXAI's terminal coding agent — a full-screen TUI that reads your codebase, edits files, runs shell commands, and drives long tasks headlessly or through the Agent Client Protocol. It left beta at 1.0.0 on 7 August 2026 and has shipped roughly a release every day or two since; the current stable build is 1.0.13, published 28 August 2026. This guide is the install, verified against the live installer scripts, the xai-org/grok-build source tree, and the official Build docs — including a long section on what actually goes wrong, because that is the part most guides skip.

How do you install Grok Build CLI?

One command per platform. Nothing else is required first — no Rust, no Node (unless you choose the npm route), no package manager.

Both shell installers drop two binaries — grok and agent — into ~/.grok/bin (%USERPROFILE%\.grok\bin on Windows). Set GROK_BIN_DIR before running if you want them somewhere else. Only x86_64 and aarch64 are supported; anything else exits with "Unsupported architecture".

To pin a specific build instead of the latest stable:

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

# Windows PowerShell
$env:GROK_VERSION="1.0.13"; irm https://x.ai/cli/install.ps1 | iex

If you would rather read the script before it touches your machine — the right instinct on a work laptop or a build box:

curl -fsSL https://x.ai/cli/install.sh -o grok-install.sh
less grok-install.sh
bash grok-install.sh

How do you install Grok CLI on Windows?

Open PowerShell (Windows PowerShell 5.1 or PowerShell 7 both work) and run:

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

What the installer actually does, in order:

1. Forces TLS 1.2 for its own downloads — Windows PowerShell 5.1 still defaults to TLS 1.0, which the artifact host rejects.
2. Detects your architecture from PROCESSOR_ARCHITECTURE. AMD64 and x86 both resolve to the x86_64 build; ARM64 gets the aarch64 build.
3. Fetches the channel pointer from https://x.ai/cli/stable. If x.ai is unreachable it silently falls back to https://storage.googleapis.com/grok-build-public-artifacts/cli.
4. Downloads the binary (a real build is around 170 MB) and copies it to grok.exe and agent.exe in %USERPROFILE%\.grok\bin.
5. Writes [cli] installer = "internal" into ~/.grok/config.toml so the auto-updater knows which path to use.
6. Prepends the bin directory to your User PATH, and patches $env:Path for the current session only.

That last point is the single most common source of "it installed but the command doesn't exist" — see the troubleshooting section below.

You do not have to run PowerShell as administrator. Everything lands under your user profile and the PATH edit is to the User scope, not Machine.

How do you install Grok Build on macOS and Linux?

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

The bash installer needs either curl or wget present — on a slim container image with neither, it exits immediately. Beyond that it handles a few things worth knowing about:

• Rosetta on Apple Silicon. In a translated shell, uname -m reports x86_64 and lies. The installer probes sysctl -n hw.optional.arm64 and installs the native arm64 build anyway.
• macOS bash users get a source ~/.bashrc line added to ~/.bash_profile if one is missing, because macOS login shells do not read .bashrc.

PATH, two ways. If ~/.grok/bin is not already on your PATH, it tries to symlink grok and agent into ~/.local/bin or /usr/local/bin — but only if that directory is already on PATH and writable. It then appends a marked block to your shell config:

# >>> grok installer >>>
export PATH="$HOME/.grok/bin:$PATH"
# <<< grok installer <<<

in ~/.bashrc, ~/.zshrc or ~/.config/fish/config.fish depending on $SHELL, backing up the original first. Re-running the installer replaces that block rather than stacking duplicates.

If your $SHELL is not bash, zsh or fish — csh, dash, a container with SHELL unset — no config file is touched and you must add the directory yourself.

Can you install Grok Build with npm or Homebrew?

npm: yes. xAI publishes @xai-official/grok, currently 1.0.13, with per-platform optional dependencies for darwin/linux/win32 on x64 and arm64. It requires Node 20 or newer and exposes the same grok binary:

npm install -g @xai-official/grok
grok --version

This is the better route if you already manage developer tooling through npm, or if the shell installer's PATH edits conflict with a dotfiles setup you control. Updates then go through npm rather than grok update.

Homebrew: no. There is no official tap or formula. Be careful here — brew install grok installs an entirely unrelated homebrew-core formula (a regular-expression tool). If you run it and then wonder why grok --version prints something odd, that is why. Use the curl installer or npm on macOS.

How do you check the install actually worked?

grok --version

# macOS / Linux
which grok

# Windows
where.exe grok

grok --version should print the version you just installed (1.0.13 at the time of writing). which / where should resolve to ~/.grok/bin/grok, a symlink into it, or your npm global bin.

Two gotchas at this step. First, if you previously installed a community wrapper — the open-source superagent-ai/grok-cli, for example — you may have a different binary named grok earlier on your PATH. Check what resolves before assuming you are running SpaceXAI's agent. Second, once you are inside the TUI, /doctor checks the current session for terminal, clipboard, colour, input, notification and sandbox problems and tells you how to fix each one; /doctor fix lists the ones it can repair automatically.

How do you authenticate Grok Build?

Run grok in a project directory. On first launch it opens your browser and signs you in through SpaceXAI OAuth at auth.x.ai, then stores credentials in ~/.grok/auth.json with owner-only (0600) permissions. Tokens refresh in the background; credentials with no server-provided expiry fall back to a 30-day lifetime.

Four documented paths, depending on where you are running:

The environment variable is XAI_API_KEY — plain, not prefixed. Older write-ups (including an earlier version of this page) cited GROK_CODE_XAI_API_KEY; that is not what the current docs specify.

Precedence matters if you have more than one credential configured. Grok resolves them highest-to-lowest: a per-model api_key/env_key in config.toml, then an active session token from ~/.grok/auth.json, then XAI_API_KEY. So if you signed in interactively and now want the API key to take effect, run grok logout first — otherwise the stored session token keeps winning.

What does the first run look like?

cd ~/code/your-project
grok

You get a full-screen TUI: scrollback above, prompt below. Type a request and press Enter. Useful things to try immediately:

• @src/main.rs — attach a file to the prompt. @src/main.rs:10-50 attaches a line range, @src/ browses a directory, and @!.github searches hidden files.
• /model grok-4.6 — switch model. You can also pass -m grok-4.6 at launch.
• /doctor — terminal and environment health check.
• /usage (alias /cost) — credit usage and billing management.
• /import-claude — pull across your existing ~/.claude permissions, env vars, MCP servers and hooks, which is the fastest way to get a Claude Code setup running here.

Headless mode is a flag away — grok -p "list every TODO and the file it is in" prints an answer and exits, which is what you want in a script or CI job. Once you are past install, the next thing worth wiring up is skills, connectors and MCP servers; we cover those in the Grok Build Skills and Connectors guide.

Why does the Grok CLI install script fail?

This is the section people actually search for. The failures below are drawn from what the installer scripts and the enterprise networking docs say happens, mapped to the symptom you will see.

Windows: "grok is not recognized" right after a successful install

By far the most common one, and it is not really a failure. The PowerShell installer writes %USERPROFILE%\.grok\bin into your User PATH and patches $env:Path in the window that ran it. Every other shell already open — cmd.exe, a second PowerShell tab, VS Code's integrated terminal, Windows Terminal panes started earlier — is still running with the old environment block.

# Fix for the current session
$env:Path = "$env:USERPROFILE\.grok\bin;$env:Path"

# Confirm the persistent value took
[Environment]::GetEnvironmentVariable('Path','User') -split ';'

Then close and reopen your terminal. If you launched PowerShell from VS Code, restart VS Code itself — it caches the environment it was started with.

Windows: the script is blocked before it runs

A plain Restricted execution policy usually does not stop irm ... | iex, because nothing is being run from a script file. What does stop it is AllSigned, or Constrained Language Mode imposed by AppLocker or WDAC on a managed device. Check both:

Get-ExecutionPolicy -List
$ExecutionContext.SessionState.LanguageMode   # want: FullLanguage

If the policy is the problem, scope a bypass to the current process only — never machine-wide:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
irm https://x.ai/cli/install.ps1 | iex

If LanguageMode is ConstrainedLanguage, no bypass you can set will help — that is enforced by device policy. Install through Git Bash with the shell script instead, or ask IT to allowlist the binary.

Windows: "Could not create SSL/TLS secure channel"

The installer sets TLS 1.2 for its own downloads, but the outer irm that fetches the script runs before that line executes. On Windows PowerShell 5.1 with TLS 1.2 not enabled by default, the fetch itself fails. Set it first:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://x.ai/cli/install.ps1 | iex

Related: irm is an alias for Invoke-RestMethod, which only exists from PowerShell 3.0 onward. On anything older, install PowerShell 7 or use the Git Bash route.

Windows: "Failed to install grok.exe"

The installer copies over grok.exe in place. If a Grok session, a background agent process, or an editor ACP integration is holding the file open, the copy fails. The script already retries by renaming the old binary to grok.exe.old first — if it still errors, something has the file genuinely locked. Close every Grok session and any editor with a Grok integration running, then re-run. As a last resort, delete %USERPROFILE%\.grok\bin\grok.exe.old and reinstall.

Windows: the install reports success but the binary vanishes

If grok --version fails and %USERPROFILE%\.grok\bin\grok.exe is missing after a run that printed no errors, check Windows Security → Protection history and your EDR agent's quarantine before reinstalling. A ~170 MB freshly-downloaded executable is exactly the shape of thing an aggressive endpoint policy holds back. The fix is an exclusion for %USERPROFILE%\.grok\bin, which on a managed device means asking IT rather than clicking through SmartScreen.

macOS / Linux: "command not found" after install

Same root cause as Windows — your current shell has the old PATH. Either restart the terminal, or source the config the installer just edited:

source ~/.zshrc        # or ~/.bashrc
grok --version

If grok is still not found, the installer probably could not identify your shell. It only writes a config block for bash, zsh and fish, based on $SHELL. Add it by hand:

export PATH="$HOME/.grok/bin:$PATH"        # add to your shell rc file
ls -l ~/.grok/bin/                          # confirm grok and agent are there

macOS / Linux: the installer exits immediately

Three quick checks. No downloader: the script needs curl or wget and exits with "Either curl or wget is required" if neither exists — common on minimal container images. Unsupported architecture: only x86_64 and aarch64 builds are published, so armv7, i686 and riscv boxes exit here. Disk space: the binary is downloaded to ~/.grok/downloads and then copied into ~/.grok/bin, so budget roughly 350 MB free in $HOME, not 170.

Any OS: corporate proxy, firewall or TLS interception

Two separate problems that look the same, so split them.

Installing needs x.ai and storage.googleapis.com reachable. The installers try the Cloudflare-fronted x.ai host first and automatically fall back to the Google Cloud Storage mirror, so a block on one of the two is survivable — a block on both is not.

Running needs, per xAI's enterprise networking docs, cli-chat-proxy.grok.com (inference proxy and settings) and auth.x.ai (OAuth2/OIDC) allowlisted. Optional but useful: api.x.ai if you authenticate with a direct API key, code.grok.com for session sync and sharing, and assets.grok.com for profile images. Everything is HTTPS on port 443, TLS 1.2 or 1.3, enforced by rustls.

The CLI honours the standard HTTPS_PROXY, HTTP_PROXY and NO_PROXY variables. If your proxy performs TLS inspection, its certificate must be trusted or every request fails with a certificate error. The documented fix is to install the proxy CA into the OS trust store; the CLI also reads an explicit bundle from GROK_EXTRA_CA_BUNDLE, falling back to SSL_CERT_FILE:

export GROK_EXTRA_CA_BUNDLE=/etc/ssl/certs/corp-ca.pem
export HTTPS_PROXY=http://proxy.corp.example:3128
export NO_PROXY=localhost,127.0.0.1
grok

One more proxy setting that bites later rather than at install time: inference uses SSE streaming with a per-chunk idle timeout that defaults to 600 seconds, so set your proxy's idle timeout to at least 10 minutes or long agent turns will be cut mid-stream.

Any OS: install works, login fails

If sign-in loops or errors, clear the cached credential and start over:

grok logout
grok login              # or: grok login --device-auth

Check for a stale XAI_API_KEY in your environment while you are there. An invalid key used to cause login to be skipped entirely — fixed in 1.0.0, but a wrong key still authenticates you as nobody useful. For deeper diagnosis, turn on logging:

GROK_LOG_FILE=/tmp/grok.log RUST_LOG=debug grok
tail -f /tmp/grok.log

Note that the GitHub mirror has issues disabled, so there is no public tracker to search. Use /feedback inside the CLI to report bugs to xAI directly.

What plan do you need, and is Grok Build free?

This is where the internet is noisier than the documentation, so here is the honest split.

What is documented. There are exactly two ways to authenticate for normal use: sign in with your grok.com account through the browser, or set XAI_API_KEY from console.x.ai. Billing is surfaced inside the CLI through /usage (alias /cost), described in the docs as viewing credit usage and managing billing. The API-key path bills at published xAI API rates. For grok-4.6, the model xAI recommends for code, those are:

The 200K threshold is the line item that matters for an agent. A terminal agent re-sends its accumulated context on every turn, so a long session drifts over 200K and the entire request reprices at double — $4/$12 rather than $2/$6. Running /compact before a session bloats is a real cost control, not housekeeping. Our Grok 4.6 pricing and API cost breakdown works through what that does to a monthly bill.

What is not documented. The widely-repeated claim that Grok Build requires a SuperGrok Heavy subscription at roughly $300/month, with a $99/month promotional tier, does not appear anywhere in xAI's own material. We checked the Build overview, the Build enterprise page and the developer pricing page: none of them names a required consumer subscription tier for the CLI, and none of them mentions $99 or $300. That figure circulated during the early-beta period and we have not been able to verify it against a primary source today. Treat it as unconfirmed rather than repeating it as fact — and if cost is the deciding factor, price the API-key path, which is published and unambiguous.

Is it free? The CLI itself is a free download and its source is public on GitHub. Inference is not free — either it draws on your grok.com account's entitlement, or it bills your xAI API credits. There is no documented free inference allowance for Grok Build.

For enterprises there is a third path: a GROK_DEPLOYMENT_KEY passed to the installer, which pulls a managed config and requirements file from your organisation's proxy, plus OIDC SSO, Zero Data Retention and version-ceiling controls.

How do you update or uninstall Grok Build CLI?

grok update                       # shell-installer builds
npm install -g @xai-official/grok@latest   # npm installs

The CLI also checks for updates on launch. That is controlled by cli.auto_update in ~/.grok/config.toml, and can be suppressed with GROK_DISABLE_AUTOUPDATER — worth setting on CI runners where you want a reproducible version. The cli.installer value the installer wrote is what tells grok update which path to take, which is why mixing the two install routes on one machine is a bad idea. /release-notes (alias /changelog) shows what changed in the version you are on.

To pin a version in a locked-down environment, install with an explicit version argument and disable the auto-updater. To remove Grok Build entirely: delete ~/.grok/bin, remove any symlinks the installer made in ~/.local/bin or /usr/local/bin, and strip the # >>> grok installer >>> block from your shell rc file. Delete the whole ~/.grok directory if you also want to discard credentials, sessions and config.

Should you switch to Grok Build?

The install is genuinely a one-liner and the release cadence since 1.0.0 has been fast — thirteen stable releases in three weeks, mostly bug fixes against real terminal-integration edge cases. If you already run Claude Code or Codex CLI, /import-claude means the evaluation costs you an afternoon rather than a re-tooling project, and how the three compare on actual work is the subject of our Grok Build vs Claude Code vs Codex CLI comparison.

A reasonable decision rule: install it, point it at a repo you know well, and watch the /usage number for a week before you move anything that matters onto it. The 200K repricing threshold is the thing most likely to surprise you, and it shows up in billing before it shows up in your workflow.

FAQ

How do I install Grok CLI?

On macOS, Linux or Git Bash run curl -fsSL https://x.ai/cli/install.sh | bash. On Windows PowerShell run irm https://x.ai/cli/install.ps1 | iex. Both place grok and agent in ~/.grok/bin and update your PATH. Verify with grok --version, then run grok in a repository to sign in.

How do I install Grok Build on Windows?

Open PowerShell — 5.1 or 7, no admin rights needed — and run irm https://x.ai/cli/install.ps1 | iex. It installs to %USERPROFILE%\.grok\bin and adds that to your User PATH. Close and reopen your terminal afterwards, or the new PATH will not be visible. Git Bash, MSYS2 and WSL can use the bash installer instead.

Why does the Grok CLI install script fail?

Most reports are not real failures — the binary installed but your open terminal still has the old PATH, so restart it. Genuine failures cluster around four causes: Constrained Language Mode or an AllSigned policy blocking iex, TLS 1.2 not enabled on Windows PowerShell 5.1, a corporate proxy blocking both x.ai and storage.googleapis.com, or a running grok.exe locking the file during the copy.

Is Grok Build CLI free?

The CLI is a free download and its Rust source is public at xai-org/grok-build. Inference is not free: it either draws on your grok.com account's entitlement or bills xAI API credits against the key in XAI_API_KEY. xAI publishes no free inference allowance for Grok Build. Check consumption inside the CLI with /usage.

What plan do I need for Grok Build?

xAI's documentation does not name a required consumer subscription tier. The two documented paths are signing in with a grok.com account or setting XAI_API_KEY from console.x.ai, billed at API rates ($2/$6 per 1M input/output on grok-4.6, doubling above 200K-token prompts). The widely-quoted "$99/month SuperGrok Heavy" requirement does not appear in any xAI source we could verify.

How do I update Grok Build CLI?

Run grok update if you used the shell installer, or npm install -g @xai-official/grok@latest if you installed through npm. The CLI also checks on launch; disable that with GROK_DISABLE_AUTOUPDATER or cli.auto_update = false in ~/.grok/config.toml. Pin a version with curl -fsSL https://x.ai/cli/install.sh | bash -s 1.0.13.

Where does Grok Build install to?

~/.grok/bin on macOS and Linux, %USERPROFILE%\.grok\bin on Windows, both containing grok and agent. Set GROK_BIN_DIR before running the installer to change it. Config lives in ~/.grok/config.toml, credentials in ~/.grok/auth.json at mode 0600, and sessions in ~/.grok/sessions/. GROK_HOME relocates the whole directory.

Can I install Grok Build with Homebrew?

No. There is no official tap or formula, and brew install grok installs an unrelated homebrew-core package — a regular-expression tool — which is a genuine trap on macOS. Use curl -fsSL https://x.ai/cli/install.sh | bash or npm install -g @xai-official/grok instead, and check which grok if you have already run the Homebrew command.

What is the current version of Grok Build CLI?

Stable is 1.0.13, published 28 August 2026. Version 1.0.0 shipped on 7 August 2026, with 1.0.10, 1.0.11 and 1.0.12 following on 24, 26 and 27 August — roughly a release every day or two. Check what you are running with grok --version and what changed with /release-notes inside the TUI.