# Overview

> What Grok Build exposes (interactive TUI, headless -p, ACP agent), who should use each surface, and the shortest path from install to a successful first turn.

- 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/README.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/01-getting-started.md`
- `crates/codegen/xai-grok-shell/README.md`
- `crates/codegen/xai-grok-pager-bin/src/main.rs`
- `crates/codegen/xai-grok-pager/src/app/cli.rs`
- `Cargo.toml`

---

---
title: "Overview"
description: "What Grok Build exposes (interactive TUI, headless -p, ACP agent), who should use each surface, and the shortest path from install to a successful first turn."
---

The shipped `grok` binary is SpaceXAI’s terminal AI coding agent. Default invocation opens the interactive TUI; `-p` / `--single` (or `--prompt-file` / `--prompt-json`) runs a non-interactive single-turn harness; `grok agent stdio` speaks Agent Client Protocol (ACP) JSON-RPC over stdin/stdout for IDEs and custom clients. The same agent runtime, tools, sessions, permissions, and config back all three surfaces.

## Product surfaces

| Surface | Entry | Process model | Primary audience |
| --- | --- | --- | --- |
| Interactive TUI | `grok` | Full-screen UI; optional positional first prompt | Day-to-day coding in a terminal |
| Headless single-turn | `grok -p "…"` / `--single` / `--prompt-file` / `--prompt-json` | One prompt, tools, stdout, exit | Scripts, CI, pipelines |
| ACP agent | `grok agent stdio` | Long-lived JSON-RPC server on stdio | IDE extensions, SDKs, host apps |

```mermaid
flowchart TB
  subgraph entry["Entry — xai-grok-pager-bin"]
    CLI["PagerArgs / Command"]
  end
  subgraph surfaces["Surfaces"]
    TUI["Interactive TUI\ngrok"]
    HL["Headless single-turn\ngrok -p"]
    ACP["ACP stdio\ngrok agent stdio"]
    AOTH["agent serve / leader /\nagent headless relay"]
  end
  subgraph runtime["Shared runtime — xai-grok-shell"]
    SESS["Sessions"]
    TOOLS["Tools + MCP"]
    AUTH["Auth + models"]
    CFG["config.toml / rules"]
  end
  CLI --> TUI
  CLI --> HL
  CLI --> ACP
  CLI --> AOTH
  TUI --> runtime
  HL --> runtime
  ACP --> runtime
  AOTH --> runtime
```

<Note>
`grok -p` (print / single-turn) is not the same path as `grok agent headless`. The latter attaches the agent to a Grok WebSocket relay for remote/headless *session* hosting. For one-shot automation, use `-p`.
</Note>

### Interactive TUI

Default when there is no subcommand and no headless prompt flags:

```bash
grok
grok "fix the failing auth test and run it"
grok --cwd ~/projects/my-app -m grok-build
```

The UI is split into **scrollback** (conversation, tool output, diffs) and **prompt** (input). Core interaction:

- `Enter` sends the prompt; tool runs stream into scrollback
- `@path` attaches files or line ranges via the fuzzy picker
- `/…` slash commands for session, model, compact, permissions, etc.
- Default permission prompts before shell and edits; `Ctrl+O`, `/always-approve`, or `--yolo` / `--always-approve` for always-approve

Use this surface when you want a human in the loop for multi-step work, review of edits, and interactive approvals.

### Headless single-turn (`-p`)

Headless mode is selected when any of `-p` / `--single`, `--prompt-json`, or `--prompt-file` is set. The binary runs `run_single_turn`, prints to stdout, and exits.

```bash
grok -p "Explain this codebase"
grok -p "Review changes for bugs" --output-format json --yolo
grok --prompt-file ./task.md --output-format streaming-json
```

| Flag / option | Role |
| --- | --- |
| `-p, --single <PROMPT>` | Prompt text (aliases include `--print`) |
| `--prompt-file <PATH>` | Prompt from file |
| `--prompt-json <JSON>` | Prompt as JSON content blocks |
| `--output-format` | `plain` (default), `json`, `streaming-json` |
| `--tools` / `--disallowed-tools` | Headless-only tool allow/deny lists |
| `--max-turns <N>` | Cap agentic turns (headless-only) |
| `--yolo` / `--always-approve` | Auto-approve tool execution |
| `-r` / `-c` / `--fork-session` | Resume, continue, or fork sessions |

Use this surface for CI reviews, scripted refactors, and anything that must not open a TUI. Prefer `XAI_API_KEY` or pre-hydrated credentials in non-browser environments.

### Agent mode (ACP)

```bash
grok agent stdio
grok agent --model grok-build --always-approve stdio
```

`grok agent stdio` runs `run_stdio_agent`: JSON-RPC over stdin/stdout (ACP session lifecycle, streaming `session/update`, tool visibility, permission requests). Related agent modes on the same subcommand:

| Mode | Command | Role |
| --- | --- | --- |
| stdio | `grok agent stdio` | IDE / client embedding (primary) |
| serve | `grok agent serve --bind 127.0.0.1:2419` | Local WebSocket server |
| headless | `grok agent headless` | Outbound WebSocket relay client |
| leader | `grok agent leader` | Shared backend for multiple clients |

Use ACP when a host process owns the UI (editor, desktop shell, custom app) and needs structured streaming rather than a terminal UI or a one-shot exit.

## Shortest path to a first turn

<Steps>
  <Step title="Install the released binary">
    ```bash
    curl -fsSL https://x.ai/cli/install.sh | bash   # macOS / Linux / Git Bash
    # Windows PowerShell:
    # irm https://x.ai/cli/install.ps1 | iex
    grok --version
    ```
    Installers place the binary under `~/.grok/bin` (and User PATH on Windows PowerShell). Pin with `bash -s <version>` or `$env:GROK_VERSION=…` as documented on Installation.
  </Step>
  <Step title="Authenticate">
    Interactive default opens a browser and writes credentials to `~/.grok/auth.json`. For CI or no-browser hosts:

    ```bash
    export XAI_API_KEY="xai-..."
    # or
    grok login --device-auth
    ```
  </Step>
  <Step title="Run one successful turn">
    <Tabs>
      <Tab title="TUI">
        ```bash
        cd /path/to/your/repo
        grok
        ```
        Type a prompt, press `Enter`, confirm tool output appears in scrollback.
      </Tab>
      <Tab title="Headless">
        ```bash
        grok -p "Summarize the top-level layout of this repository"
        ```
        Expect plain text on stdout and process exit when the turn finishes.
      </Tab>
      <Tab title="ACP smoke">
        ```bash
        grok agent stdio
        ```
        Leave the process running; an ACP client drives `initialize` → `session/new` → `session/prompt`. Without a client, use the TUI or `-p` for a human-visible first turn.
      </Tab>
    </Tabs>
  </Step>
</Steps>

<Check>
First-turn success signals: `grok --version` prints a version; auth does not loop; a prompt produces model text and (when tools run) streamed tool results in the TUI or headless output.
</Check>

## Shared runtime and home layout

All surfaces share the agent stack under `xai-grok-shell` (sessions, tools, MCP, models, memory) and workspace tooling under `xai-grok-tools` / `xai-grok-workspace`. User state defaults to `~/.grok` (override with `GROK_HOME`).

| Path | Purpose |
| --- | --- |
| `~/.grok/bin/` | Released binary install location |
| `~/.grok/auth.json` | OAuth / session credentials |
| `~/.grok/config.toml` | Main config (`[cli]`, `[models]`, `[ui]`, MCP, features, …) |
| `~/.grok/sessions/` | Persisted conversations (by working directory) |
| `~/.grok/memory/`, `skills/`, `plugins/`, `agents/` | Cross-session memory and extensions |
| Project `.grok/`, `AGENTS.md` | Repo-local config, skills, and instruction files |

Config precedence (high → low): CLI flags → environment variables → user `config.toml` → managed/requirements config → built-in defaults. Models can be SpaceXAI defaults or BYOK / OpenAI-compatible / Ollama endpoints—provider choice is configuration, not a hard-wired host requirement for every deployment.

## Repository composition (this tree)

This repository is the Rust workspace for the CLI/TUI and agent runtime (periodically synced from the SpaceXAI monorepo).

| Path | Role |
| --- | --- |
| `crates/codegen/xai-grok-pager-bin` | Composition root; builds `xai-grok-pager` (released as `grok`) |
| `crates/codegen/xai-grok-pager` | TUI, CLI parse (`PagerArgs` / `Command`), headless single-turn |
| `crates/codegen/xai-grok-shell` | Agent runtime: stdio ACP, leader, serve, relay headless |
| `crates/codegen/xai-grok-tools` | Built-in tools (shell, edit, search, web, subagents, …) |
| `crates/codegen/xai-grok-workspace` | Filesystem, VCS, execution, checkpoints |
| `crates/codegen/xai-grok-pager/docs/user-guide/` | In-tree user guide (source for many product docs) |

From-source build (maintainer path):

```bash
cargo run -p xai-grok-pager-bin              # build + launch
cargo build -p xai-grok-pager-bin --release  # target/release/xai-grok-pager
```

Root `Cargo.toml` is generated; prefer per-crate manifests. External contributions are not accepted (see `CONTRIBUTING.md`).

## Common launch flags (all surfaces)

| Flag | Effect |
| --- | --- |
| `-m, --model <ID>` | Model selection |
| `--cwd <PATH>` | Working directory |
| `--rules <TEXT>` | Extra system-prompt rules |
| `--yolo` / `--always-approve` | Auto-approve tools |
| `--sandbox <PROFILE>` | OS isolation profile |
| `-r` / `-c` / `-s` | Resume / continue / new session UUID |
| `-w, --worktree` | Session in a new git worktree |

Top-level management commands include `login`, `logout`, `mcp`, `plugin`, `memory`, `models`, `sessions`, `inspect`, `setup`, `update`, `export`, and `trace`—see CLI reference.

## Next

<CardGroup>
  <Card title="Installation" href="/installation">
    Install and update the released binary; PATH under ~/.grok/bin; version pins.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    First interactive session: auth, prompts, @ attachments, cancel, scrollback.
  </Card>
  <Card title="Authentication" href="/authentication">
    Browser OAuth, device-code, XAI_API_KEY, auth.json, token refresh.
  </Card>
  <Card title="Headless mode" href="/headless-mode">
    -p flags, output formats, tool filters, CI patterns.
  </Card>
  <Card title="Agent mode (ACP)" href="/agent-mode">
    grok agent stdio, JSON-RPC lifecycle, serve/relay options.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Full command and shared runtime flag inventory.
  </Card>
</CardGroup>