# Installation

> Install and update the released grok binary on macOS, Linux, and Windows; PATH layout under ~/.grok/bin; version pin flags; verify with grok --version.

- Repository: xai-org/grok-build
- GitHub: https://github.com/xai-org/grok-build
- Human docs: https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458
- Complete Markdown: https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/llms-full.txt

## Source Files

- `README.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/01-getting-started.md`
- `crates/codegen/xai-grok-pager/scripts/install.sh`
- `crates/codegen/xai-grok-pager/scripts/install.ps1`
- `crates/codegen/xai-grok-update/src/auto_update.rs`
- `crates/codegen/xai-grok-update/src/version.rs`
- `crates/codegen/xai-grok-paths/src/lib.rs`

---

---
title: "Installation"
description: "Install and update the released grok binary on macOS, Linux, and Windows; PATH layout under ~/.grok/bin; version pin flags; verify with grok --version."
---

Released `grok` binaries install into `$GROK_HOME` (default `~/.grok`) via platform bootstrap scripts hosted at `https://x.ai/cli`, or via npm (`@xai-official/grok`). The scripts place a managed binary under `bin/`, record `installer = "internal"` in `config.toml`, and wire PATH so `grok` and `agent` resolve immediately or after a shell restart.

## Supported platforms

| OS | Architectures | Installer |
|----|---------------|-----------|
| macOS | `x86_64`, `aarch64` | `install.sh` |
| Linux | `x86_64`, `aarch64` | `install.sh` |
| Windows | `x86_64`, `aarch64` | `install.ps1` (native), or `install.sh` under Git Bash / MSYS2 / Cygwin |
| WSL | Linux arch of the guest | `install.sh` (Linux binary) |

Unsupported `uname` OS/arch pairs exit with an explicit error. Artifacts are named `grok-<version>-<os>-<arch>` (`.exe` on Windows).

## Install latest stable

<Tabs>
<Tab title="macOS / Linux / Git Bash">

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

Requires `curl` or `wget`. The script probes `https://x.ai/cli/<channel>` first, then falls back to the public GCS mirror when the primary is unreachable.

</Tab>
<Tab title="Windows PowerShell">

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

Windows-only. PowerShell 5.1 enables TLS 1.2 automatically for the download. Adds `%USERPROFILE%\.grok\bin` to the User PATH and the current session.

</Tab>
<Tab title="npm">

```bash
npm i -g @xai-official/grok
```

Platform packages ship optional native binaries. Updates later go through `npm` or `grok update` when the installer is detected as `npm`.

</Tab>
</Tabs>

## Pin a version at install time

Version strings must match semver: `X.Y.Z` or `X.Y.Z-suffix` (for example `0.1.42`, `0.1.151-alpha.2`).

<CodeGroup>

```bash title="install.sh"
curl -fsSL https://x.ai/cli/install.sh | bash -s 0.1.42
```

```powershell title="install.ps1 (env)"
$env:GROK_VERSION="0.1.42"; irm https://x.ai/cli/install.ps1 | iex
```

```powershell title="install.ps1 (param)"
& ([scriptblock]::Create((irm https://x.ai/cli/install.ps1))) -Version 0.1.42
```

</CodeGroup>

Invalid formats fail before any download.

## Verify

```bash
grok --version
# aliases: grok -v, grok -V, grok version
```

`--version` / `-v` / `-V` print the compiled version plus an optional channel label derived from the cached stable pointer (for example ` [stable]` or ` [alpha]`). After install, prefer the managed path if PATH is not refreshed yet:

```bash
~/.grok/bin/grok --version          # Unix
%USERPROFILE%\.grok\bin\grok.exe --version   # Windows
```

On Unix, the bootstrap script smoke-tests the downloaded binary with `--version` before swapping links; a failed smoke test aborts and leaves the previous install in place.

## PATH and on-disk layout

Default home is `~/.grok` (canonicalized). Override with `GROK_HOME`. Binary directory defaults to `$GROK_HOME/bin` and can be overridden with `GROK_BIN_DIR` at install time only.

:::files
~/.grok/
├── bin/
│   ├── grok          # Unix: symlink → ../downloads/grok-<ver>-<platform>
│   ├── agent         # same target (or .exe copies on Windows)
│   ├── grok.exe      # Windows copies (not symlinks)
│   └── agent.exe
├── downloads/
│   └── grok-<version>-<os>-<arch>[.exe]
├── completions/      # bash / zsh / powershell scripts (best-effort)
├── config.toml       # [cli] installer, channel, auto_update, …
├── version.json      # update TTL cache
├── managed_config.toml   # deployment-key installs only
└── requirements.toml     # deployment-key installs only
:::

### Unix install behavior

1. Download into `~/.grok/downloads/grok-<platform>` (versioned file after install path runs).
2. `chmod +x`, smoke-test `--version`.
3. Symlink `~/.grok/bin/grok` and `~/.grok/bin/agent` to a **relative** target (`../downloads/...`) when bin and downloads share a parent — survives Docker bind-mounts with a different `$HOME`.
4. Generate shell completions under `~/.grok/completions/{bash,zsh}` and Fish’s auto-load dir when writable.
5. Write/update `[cli]` in `config.toml` with `installer = "internal"` and optional non-stable `channel`.
6. If `~/.grok/bin` is not already on `PATH`, try a writable dir already on PATH (`~/.local/bin`, then `/usr/local/bin`) and symlink `grok`/`agent` there.
7. Append or refresh a marked block in `~/.bashrc`, `~/.zshrc`, or Fish config so `$HOME/.grok/bin` is on PATH for future sessions. zsh also adds completion `fpath`; bash sources the bash completion file when readable.

### Windows install behavior

1. Download `grok-<version>-windows-<arch>.exe` into `%USERPROFILE%\.grok\downloads\`.
2. **Copy** to `bin\grok.exe` and `bin\agent.exe` (symlinks need Developer Mode; locked executables are renamed to `*.old` then replaced).
3. Prepend `%USERPROFILE%\.grok\bin` to the User `Path` and the current process `Path`.
4. Same `[cli]` config persistence as Unix.

Canonical application path used by the runtime for restarts: `$GROK_HOME/bin/grok` or `grok.exe`.

## Update after install

```bash
grok update
```

`grok update` reuses the recorded installer (`internal`, `npm`, or `gh-release`). For the default CDN install, it downloads the channel pointer target and rewrites the managed bin links.

| Flag | Behavior |
|------|----------|
| `--check` | Report whether an update is available; no install |
| `--json` | Machine-readable status; **requires** `--check` |
| `--force-reinstall` | Re-download even when already current |
| `--version <semver>` | Install that exact version (pin) |
| `--alpha` | Switch channel to `alpha` and update |
| `--stable` | Switch channel to `stable` and update |
| `--enterprise` | Switch channel to `enterprise` (hidden flag) |

Channel flags are mutually exclusive. Switching persists `cli.channel` in `config.toml`.

### Pin after install

```bash
grok update --version 0.1.150
```

Pinned installs set `cli.auto_update = false` so automatic upgrades do not override the pin. Re-enable auto-update in config (or accept an interactive update prompt path) when you want channel tracking again.

### Status check

```bash
grok update --check
grok update --check --json
```

JSON fields include `currentVersion`, `latestVersion`, `updateAvailable`, `installer`, `channel`, `autoUpdate`, and optional `error`.

npm users can also run:

```bash
npm i -g @xai-official/grok@latest
```

## Release channels and artifact URLs

| Env / config | Values | Default |
|--------------|--------|---------|
| `GROK_CHANNEL` (install scripts) | `stable`, `alpha`, `enterprise` | `stable` |
| `cli.channel` (`config.toml`) | same | `stable` |

Channel pointer (plain-text semver):

- Primary: `https://x.ai/cli/<channel>`
- Fallback: `https://storage.googleapis.com/grok-build-public-artifacts/cli/<channel>`

Binary artifact:

- `https://x.ai/cli/grok-<version>-<os>-<arch>[.exe]`
- Same path under the GCS fallback base

Alpha channel resolution takes the semver-greater of the alpha and stable pointers (and the same rule for npm/`gh` backends) so alpha installs are not stranded behind a newer stable.

## Auto-update

When `cli.auto_update` is unset, the first update check treats it as enabled and persists `true`. Explicit `cli.auto_update = false` skips automatic checks.

Suppression gates (any one disables auto-update checks):

- Debug builds (`debug_assertions`)
- `--no-auto-update` (hidden session flag)
- `GROK_DISABLE_AUTOUPDATER` set in the environment

Version freshness is cached in `~/.grok/version.json` with a ~30 minute TTL. Background TUI/leader paths may spawn `grok update` as a detached child when the on-disk install lags the channel pointer; internal/gh-release installs allow intentional channel rollbacks, while npm never auto-downgrades (stale registry safety).

`cli.minimum_version` (any config layer) can refuse startup below a floor and, when auto-update is on, install `max(latest, minimum)`.

## Installer environment variables

| Variable | Used by | Role |
|----------|---------|------|
| `GROK_HOME` | runtime | Config/binary root; default `~/.grok` |
| `GROK_BIN_DIR` | install scripts | Override install bin directory |
| `GROK_CHANNEL` | install scripts | Channel pointer (`stable` / `alpha` / `enterprise`) |
| `GROK_VERSION` | `install.ps1` | Pin version when using `irm \| iex` |
| `GROK_DEPLOYMENT_KEY` | install scripts | Auth for deployment config pull; takes precedence over `auth.json` tokens |
| `GROK_PROXY_URL` | install scripts | Deployment config API base (default `https://cli-chat-proxy.grok.com/v1`) |
| `GROK_INSTALLER` | updater | Force `npm` / `internal` / `gh-release` |
| `GROK_MANAGED_BY_NPM` / `GROK_MANAGED_BY_INTERNAL` | updater | Installer detection hints |
| `GROK_DISABLE_AUTOUPDATER` | runtime | Disable automatic update checks |
| `NPM_TOKEN` | npm install path | Optional private registry auth for npm-backed updates |

Without a deployment key, install still works for public artifacts. If present, installers may also write `managed_config.toml` and `requirements.toml` from the deployment config endpoint.

## Completions

Best-effort generation at install time:

| Shell | Path |
|-------|------|
| bash | `~/.grok/completions/bash/grok.bash` |
| zsh | `~/.grok/completions/zsh/_grok` |
| fish | `~/.config/fish/completions/grok.fish` |
| PowerShell | `~/.grok/completions/powershell/grok.ps1` |

Regenerate anytime:

```bash
grok completions bash
grok completions zsh
grok completions fish
grok completions powershell
```

## Failure modes

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `Either curl or wget is required` | No downloader on PATH | Install `curl` or `wget` |
| `Unsupported OS` / architecture | Platform not published | Use a supported host or [build from source](/build-from-source) |
| Primary URL unreachable note | Cloudflare path down | Script falls back to GCS automatically |
| Binary download 404 | Version/platform not published | Pin a known version; check channel |
| `downloaded grok failed to run` (Unix) | Corrupt/wrong-arch binary | Previous install kept; retry or pin another version |
| Windows `Failed to install grok.exe` | File lock / permissions | Close running `grok`, retry; check antivirus locks |
| `grok: command not found` | PATH not updated | Restart shell; or `export PATH="$HOME/.grok/bin:$PATH"`; Windows: open a new terminal after User PATH write |
| `Auto-update is not available for manual installations` | No known installer recorded | Re-run bootstrap install, or set `cli.installer` / `GROK_INSTALLER` |
| Pinned version never upgrades | `auto_update=false` after `--version` pin | `grok update` without pin, or set `cli.auto_update = true` |

## Build-from-source note

Workspace builds produce `xai-grok-pager` under `target/release/`; official installers ship the same product as `grok`. Source builds are not managed by the CDN installer layout. See [Build from source](/build-from-source).

## Next

<CardGroup>
<Card title="Quickstart" href="/quickstart">
Launch the TUI, authenticate, and run a first turn.
</Card>
<Card title="Authentication" href="/authentication">
Browser OAuth, device code, and `XAI_API_KEY` for CI.
</Card>
<Card title="Configure Grok" href="/configure-grok">
`config.toml` precedence, channels, and auto-update keys.
</Card>
<Card title="CLI reference" href="/cli-reference">
Full `grok` command and flag surface including `update`.
</Card>
<Card title="Build from source" href="/build-from-source">
Rust toolchain pin, `cargo run -p xai-grok-pager-bin`, binary naming.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
Terminal, auth, and runtime diagnostics after install.
</Card>
</CardGroup>