Install Grok Build on macOS, Linux or Windows in two minutes

Before you install

Grok Build is a terminal app from SpaceXSI (formerly xAI). Prebuilt binaries exist for macOS, Linux and Windows. You need:

• A terminal: Terminal or iTerm on macOS, any shell on Linux, PowerShell or Git Bash on Windows.
• A web browser for the first sign-in, or an API key if you are setting it up on a server.
• An account. Grok Build is free to try, and the X Subscription Plus plan ($8 per month) and higher tiers add more usage.

Install commands

1. macOS, Linux or Git Bash: run curl -fsSL https://x.ai/cli/install.sh | bash
2. Windows PowerShell: run irm https://x.ai/cli/install.ps1 | iex
3. Check it worked: run grok --version. If a version number prints, the install succeeded.

Both commands come from the official Grok Build page and the GitHub repo. The installer puts the program in ~/.grok/bin, according to a third-party setup guide.

Developers can also build from source. That needs a Rust toolchain (installed and pinned through rustup), DotSlash (cargo install dotslash) and protoc. macOS and Linux are the supported build hosts. Windows builds are “best-effort,” so Windows users should use the prebuilt binary.

First run and sign-in

1. Open a terminal in your project folder, not your home folder.
2. Run grok.
3. A browser window opens so you can sign in, usually at grok.com.
4. After sign-in, the terminal interface starts. Credentials are stored in ~/.grok/auth.json.

Why the project folder matters: in July 2026, running Grok Build could upload the whole current directory to company cloud storage. SpaceXSI disabled that the same day and says Build can now run fully locally. Starting in the project folder is still the safer habit, because the agent can read and edit files where it runs.

By default, Grok Build uses plan mode: it proposes a plan and makes no edits until you approve it.

Updating and checking your setup

• grok update updates Grok Build to the latest version.
• grok doctor checks your terminal setup and reports problems.
• grok --version shows the installed version.

Update often. SpaceXSI ships features quickly, and new models such as Grok 4.7 arrive in Grok Build on release day.

Using an API key in CI

A browser sign-in does not work on build servers. For CI, set the XAI_API_KEY environment variable instead, and use the headless mode for scripts and pipelines.

1. Create an account at console.x.ai.
2. Load credits. The API is prepaid, and requests are rejected when credits run out.
3. Generate a key on the API Keys page.
4. Store it as a secret in your CI system and expose it as XAI_API_KEY.

Usage through an API key is billed at API rates, not from your subscription pool. The grok-build-0.1 model costs $1 per million input tokens and $2 per million output tokens.

Config file and permissions

Grok Build keeps its settings in ~/.grok/config.toml. That is where MCP servers are configured, for connections to tools such as Linear, Sentry or Postgres.

Per-project conventions go in an AGENTS.md file in each directory. A third-party guide lists these permission modes: default, acceptEdits, auto, dontAsk, bypassPermissions and plan. Useful flags include --worktree, --no-plan and --no-subagents. Avoid bypassPermissions unless you run Build in a sandbox.

Common problems

• “grok: command not found”: open a new terminal so your shell reloads its path, and check that ~/.grok/bin is on your PATH.
• Display looks broken: run grok doctor to check terminal support.
• Sign-in window does not open: on a remote machine, use XAI_API_KEY instead.
• API key rejected: check that your console account has credits loaded.
• Grok 4.7 Fast missing: Fast is not part of the free tier.
• Usage ran out: paid plans share one weekly pool with Grok chat and Cursor. Heavy use in one place leaves less for the others.

Questions people ask