# Quickstart

> First interactive session: launch grok, authenticate, send a prompt, use @ file attachments, cancel turns, and confirm tool output in the TUI scrollback.

- 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

- `crates/codegen/xai-grok-pager/docs/user-guide/01-getting-started.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/03-keyboard-shortcuts.md`
- `crates/codegen/xai-grok-pager/src/app/cli.rs`
- `crates/codegen/xai-grok-pager/src/startup.rs`
- `crates/codegen/xai-grok-shell/README.md`
- `crates/codegen/xai-grok-tools/src/lib.rs`

---

---
title: "Quickstart"
description: "First interactive session: launch grok, authenticate, send a prompt, use @ file attachments, cancel turns, and confirm tool output in the TUI scrollback."
---

`grok` with no subcommand starts the interactive **Grok Build TUI** (`PagerArgs` in the pager binary): a full-screen agent screen with a **scrollback** transcript and a bottom **prompt** composer. The first successful session is: install on `PATH`, authenticate into `~/.grok/auth.json` (or `XAI_API_KEY`), send a turn, optionally attach files with `@`, cancel with `Ctrl+C` when needed, and verify tool results streaming into scrollback.

<Info>
Requires a released `grok` binary on `PATH` (`grok --version`). Install and update steps live on the [Installation](/installation) page.
</Info>

## Prerequisites

| Check | Command / path | Expected signal |
|-------|----------------|-----------------|
| Binary installed | `grok --version` | Version string, exit 0 |
| Writable home layout | `~/.grok/` | Created on first run for auth, config, sessions |
| Project directory | `cd` into a repo (or use `--cwd`) | Tools operate relative to that working directory |

```bash
grok --version
```

## First interactive session

<Steps>
<Step title="Launch the TUI">
From a project directory:

```bash
grok
```

Or seed the first turn with a positional prompt (interactive only; not headless `-p`):

```bash
grok "summarize this repo and list the top risks"
```

Useful first-session flags:

| Flag | Effect |
|------|--------|
| `--cwd <PATH>` | Working directory (default: current directory) |
| `-m` / `--model <MODEL>` | Model ID for this session |
| `--rules <TEXT>` | Extra rules appended to the system prompt |
| `--always-approve` (aliases: `--yolo`, `--dangerously-skip-permissions`) | Auto-approve tool executions |
| `-c` / `--continue` | Continue the most recent session for this cwd |
| `-r` / `--resume [SESSION_ID]` | Resume a session (most recent if ID omitted) |
| `-w` / `--worktree [NAME]` | Start in a new git worktree; use `--worktree=name` when also passing a positional prompt |
| `--worktree-ref` / `--ref` | Base ref for the worktree (requires `--worktree`) |
| `--minimal` / `--fullscreen` | Sticky screen mode preference under `[ui] screen_mode` in `~/.grok/config.toml` |

```bash
grok --cwd ~/projects/my-app -m grok-build --rules "Prefer TypeScript. Prefer functional components."
```

<Warning>
With `--worktree`, pass the name as `--worktree=feat` (equals form) when a positional prompt follows. `grok -w "refactor X"` treats `"refactor X"` as the worktree label, not the prompt.
</Warning>
</Step>

<Step title="Authenticate">
On first launch without credentials, Grok starts browser OAuth (SpaceXAI at `auth.x.ai` / grok.com sign-in). Successful login writes credentials to `~/.grok/auth.json`. Tokens refresh in the background; when refresh fails, the TUI prompts you to sign in again. Credentials without a server-provided expiry fall back to a **30-day** lifetime.

Re-auth or switch account:

```bash
grok login
```

| Flow | Command | When to use |
|------|---------|-------------|
| Browser OAuth (default) | `grok` or `grok login` / `grok login --oauth` | Local machine with a browser |
| Device code | `grok login --device-auth` (alias `--device-code`) | Headless / remote / no browser on the target machine |
| API key | `export XAI_API_KEY="xai-..."` then `grok` | CI and non-interactive hosts ([console.x.ai](https://console.x.ai)) |
| Sign out | `grok logout` | Clears cached credentials |

<Note>
A stored interactive session token takes precedence over `XAI_API_KEY`. Use `grok logout` (or remove `~/.grok/auth.json`) when you need the API key path.
</Note>

Verification: the welcome/agent screen loads without a login loop, and a short prompt returns a model response.
</Step>

<Step title="Send a prompt">
The TUI has two panes:

- **Scrollback** — conversation history: user prompts, agent markdown, thinking blocks, tool calls (including shell output and file diffs), task lists.
- **Prompt** — composer at the bottom.

| Action | Binding |
|--------|---------|
| Send | `Enter` (prompt focused) |
| Newline | `Shift+Enter` or `Alt+Enter` |
| Multiline toggle | `Ctrl+M` (prompt focused) |
| Focus scrollback ↔ prompt | `Tab` (`Space` or letter keys also focus the prompt from scrollback in simple mode) |
| Command palette | `Ctrl+P` or `?` |

Type a task and press `Enter`. The agent may read files, run shell commands, search, and edit code. Each tool invocation streams into scrollback in real time.

Slash commands (type `/` for autocomplete):

```text
/model grok-build
/compact
/always-approve
/new
```
</Step>

<Step title="Attach files with @">
In the prompt, type `@` to open the fuzzy file picker. Select with `Tab` or `Enter`.

```text
@src/main.rs              # whole file
@src/main.rs:10-50        # line range
@src/                     # directory browse (trailing /)
```

Defaults:

- Respects `.gitignore`
- Hides dotfiles

Prefix the query with `!` to include ignored/hidden paths:

```text
@!.github
@!.env
@!.vscode/settings.json
```

Attached paths are included with the user message so the model can ground on that content without an extra discovery turn.
</Step>

<Step title="Cancel a running turn">
While a turn is running:

| State | Key | Effect |
|-------|-----|--------|
| Turn running, empty prompt | `Ctrl+C` | Cancel the current turn |
| Turn running, non-empty draft | `Ctrl+C` | Clears the draft first; second `Ctrl+C` on empty prompt cancels |
| Turn running | `Esc` | **No-op** (does not cancel) |
| Turn cancelling | `Esc` | Re-sends cancel (retry if first ack was lost) |
| Idle, non-empty prompt | `Esc` twice within **800ms** | Clear prompt (text saved to prompt history) |
| Idle, empty prompt + messages | `Esc` twice within **800ms** | Open rewind picker (same as `/rewind`) |

Always-approve (skip per-tool prompts): `Ctrl+O`, `/always-approve`, or launch with `--always-approve` / `--yolo`.

Mid-turn follow-ups: plain `Enter` with text **queues** a message for after the current turn; platform-specific **send now** chords cancel-and-send (see [Keyboard shortcuts](/keyboard-shortcuts)).
</Step>

<Step title="Confirm tool output in scrollback">
Focus the scrollback (`Tab`) and inspect streamed tool blocks.

| Scrollback content | What to check |
|--------------------|---------------|
| Tool calls | Command, paths, status, streamed stdout/stderr |
| File edits | Inline diffs before/after apply |
| Agent messages | Markdown answers and follow-up questions |
| Thinking blocks | Collapsible reasoning (optional) |
| Task lists | `todo_write` progress |

| Action | Simple mode | Vim mode (`/vim-mode` or `[ui].vim_mode = true`) |
|--------|-------------|--------------------------------------------------|
| Select entry | `Up` / `Down` | `k` / `j` |
| Collapse / expand | `Left` / `Right` | `h` / `l` (or `e`) |
| Fullscreen viewer | `Enter` | `Enter` |
| Copy content / metadata | — | `y` / `Y` |
| Jump prev/next user turn | `Shift+Left` / `Shift+Right` | `H` / `L` |

By default Grok **asks before** shell commands and file edits. Approve when prompted, or use always-approve for trusted local work.

Common built-in tools you will see in scrollback:

| Tool | Role |
|------|------|
| `read_file` / `search_replace` | Read and line-precise edits |
| `grep` | Regex search (ripgrep) |
| `list_dir` | Directory listing |
| `run_terminal_command` | Shell execution |
| `web_search` / `web_fetch` | Web research (fetch may be gated by config/env) |
| `todo_write` | Task list |
| `spawn_subagent` | Parallel child agents |
| `memory_search` | Cross-session memory (when memory is enabled) |

Verification signals for a healthy first turn:

1. Your prompt appears as a sticky user header in scrollback.
2. Tool blocks stream while the agent works (not only after completion).
3. Shell/file tools either prompt for permission or run under always-approve.
4. Final agent text renders with markdown/syntax highlighting.
5. Session data appears under `~/.grok/sessions/` (grouped by encoded cwd).
</Step>
</Steps>

## Session basics after the first turn

Every conversation is a **session**, auto-saved under `~/.grok/sessions/` (override base with `GROK_HOME`).

| Goal | Interactive | CLI |
|------|-------------|-----|
| New session | `Ctrl+N` (double-press) or `/new` | Start `grok` again |
| Resume picker | `Ctrl+S` or `/resume` | `grok --resume [ID]` |
| Continue latest for cwd | — | `grok -c` |
| Compact history | `/compact` | — |

Project instructions: place `AGENTS.md` (or `CLAUDE.md` for compatibility) in the repo; deeper paths win. See [Project rules and memory](/project-rules-and-memory).

## Troubleshooting the first session

| Symptom | What to try |
|---------|-------------|
| Login loop / expired credentials | `grok login`, or `grok logout` then login; check `~/.grok/auth.json` |
| No browser on remote host | `grok login --device-auth` or `XAI_API_KEY` |
| API key ignored | Interactive session token wins — `grok logout` first |
| Tools hang waiting for approval | Approve prompts, or `Ctrl+O` / `--always-approve` |
| Cancel does nothing with Esc | Use `Ctrl+C`; Esc does not cancel a running turn |
| Bad terminal colors / keys | `/terminal-setup`; see [Troubleshooting](/troubleshooting) |
| Wrong project files | Relaunch with `--cwd` or start from the repo root |

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
Install and update the `grok` binary; `~/.grok/bin` PATH layout; `grok --version`.
</Card>
<Card title="Authentication" href="/authentication">
Browser OAuth, device-code, `XAI_API_KEY`, `grok login` / `logout`, `auth.json` refresh.
</Card>
<Card title="Keyboard shortcuts" href="/keyboard-shortcuts">
Focus, cancel vs Esc, vim mode, send-now chords, mouse.
</Card>
<Card title="Slash commands" href="/slash-commands">
`/model`, `/new`, `/resume`, `/compact`, `/always-approve`, and skill-provided commands.
</Card>
<Card title="Sessions" href="/sessions">
Resume, continue, fork, compact, export, and on-disk layout under `~/.grok/sessions/`.
</Card>
<Card title="Permissions and safety" href="/permissions-and-safety">
Allow/deny/ask rules, always-approve modes, hooks, and sandbox interaction.
</Card>
<Card title="Headless mode" href="/headless-mode">
Non-interactive `-p` / `--single` for scripts and CI after the interactive path works.
</Card>
<Card title="CLI reference" href="/cli-reference">
Full flag and subcommand surface for the `grok` binary.
</Card>
</CardGroup>