Documentation 2026-07-02 06:57 UTC to 2026-07-04 20:00 UTC

1#### CLI

2 

3# CLI Reference

4 

5Running `grok` with no arguments starts the interactive TUI. This page lists the subcommands and the flags you are most likely to use; run `grok --help` or `grok <subcommand> --help` for the complete set.

6 

7## Subcommands

8 

9| Command | What it does |

10| ------- | ------------ |

11| `grok login` | Sign in. `--device-auth` uses device-code authentication for headless or remote environments |

12| `grok logout` | Sign out and clear cached credentials |

13| `grok inspect [--json]` | Show the configuration Grok discovers for this directory: rules, skills, plugins, hooks, and MCP servers |

14| `grok models` | List available models |

15| `grok mcp <list\|add\|remove\|doctor>` | Manage MCP servers — see [MCP Servers](/build/features/mcp-servers) |

16| `grok plugin <list\|install\|uninstall\|update\|enable\|disable\|details\|validate>` | Manage plugins |

17| `grok plugin marketplace <list\|add\|remove\|update>` | Manage marketplace sources |

18| `grok sessions <list\|search\|delete>` | List, search, or delete sessions — see [Sessions](/build/features/sessions) |

19| `grok export <session-id> [output]` | Export a session transcript as Markdown |

20| `grok import [targets...]` | Import sessions from Claude Code |

21| `grok memory clear [--workspace\|--global\|--all]` | Clear cross-session memory files |

22| `grok worktree <list\|show\|rm\|gc>` | Manage git worktrees created for sessions — see [Worktrees](/build/features/worktrees) |

23| `grok dashboard` | Open the [Agent Dashboard](/build/features/dashboard) |

24| `grok agent stdio` | Run as an ACP agent over stdin/stdout — see [Headless & Scripting](/build/cli/headless-scripting#acp) |

25| `grok wrap <command...>` | Run a command in a local PTY that forwards OSC 52 clipboard writes — see [Terminal Support](/build/cli/terminal-support) |

26| `grok update` | Check for updates or install a specific version (`--check`, `--version <V>`, `--alpha`, `--stable`) |

27| `grok version` | Print version information |

28| `grok completions <shell>` | Generate shell completion scripts |

29| `grok setup` | Fetch and install managed configuration |

30 

31## Common flags

32 

33Flags for headless runs (`-p`, `--output-format`, and related) are covered in [Headless & Scripting](/build/cli/headless-scripting).

34 

35| Flag | What it does |

36| ---- | ------------ |

37| `--cwd <PATH>` | Working directory |

38| `-r, --resume [<ID>]` | Resume a session by ID, or the most recent if omitted |

39| `-c, --continue` | Continue the most recent session for the current directory |

40| `-s, --session-id <UUID>` | Use a specific UUID for a new session |

41| `--fork-session` | When resuming, fork into a new session ID |

42| `-w, --worktree [<NAME>]` | Start the session in a new git worktree |

43| `--ref <REF>` | Branch, tag, or commit to base the worktree on |

44| `-m, --model <MODEL>` | Model ID to use |

45| `--effort <LEVEL>` | Reasoning effort |

46| `--always-approve` | Auto-approve all tool executions (alias `--yolo`) |

47| `--allow <RULE>`, `--deny <RULE>` | Permission rules — see [Enterprise Deployments](/build/enterprise#permissions) |

48| `--sandbox <PROFILE>` | Sandbox profile — see [Enterprise Deployments](/build/enterprise#sandbox) |

49| `--rules <TEXT>` | Extra rules appended to the system prompt |

50| `--system-prompt-override <TEXT>` | Replace the system prompt entirely |

51| `--tools <LIST>`, `--disallowed-tools <LIST>` | Allow or remove built-in tools |

52| `--max-turns <N>` | Maximum number of agent turns |

53| `--no-plan`, `--no-subagents`, `--no-memory`, `--disable-web-search` | Disable a feature for this session |

54| `--experimental-memory` | Enable cross-session memory |

55| `--oauth` | Use OAuth when the welcome screen starts authentication |

56 

57Claude Code flag names are accepted as aliases where they overlap: `--allowedTools`, `--disallowedTools`, `--append-system-prompt`, `--system-prompt`, and `--dangerously-skip-permissions`.

1#### CLI

2 

3# Terminal Support

4 

5Grok draws its interface with terminal escape sequences for color, clipboard, mouse, and full-screen control, and some terminals, multiplexers, and SSH sessions handle these differently. Run `/terminal-setup` (aliases `/terminal-check`, `/terminal-info`) inside Grok to see what was detected, which clipboard routes are active, and any issues with fixes.

6 

7## Colors look wrong

8 

9Set `COLORTERM=truecolor` in your shell profile. Inside tmux, also enable 24-bit RGB:

10 

11```text

12# ~/.tmux.conf

13set -g default-terminal "tmux-256color"

14set -as terminal-features ",*:RGB"

15set -g set-clipboard on

16set -g allow-passthrough on

17```

18 

19The last two lines also fix clipboard and notification passthrough; reload with `tmux source-file ~/.tmux.conf`.

20 

21## Copy does not reach my clipboard

22 

23Grok writes to the native OS clipboard, to the tmux paste buffer inside tmux, and emits OSC 52 for remote cases (SSH, containers, Linux). Two common blockers:

24 

25* iTerm2 ignores OSC 52 until you enable Settings → General → Selection → "Applications in terminal may access clipboard".

26* Apple Terminal ignores OSC 52 entirely, so copies over SSH cannot reach your local clipboard. Wrap the remote command instead: `grok wrap ssh user@host` runs it in a local PTY that intercepts OSC 52 and writes to your clipboard. The same works for `grok wrap docker exec ...` and `grok wrap kubectl exec ...`. `grok wrap` is experimental.

27 

28## Keyboard chords do not work

29 

30* WezTerm: add `config.enable_kitty_keyboard = true` to `wezterm.lua`, then restart — this fixes `Ctrl+Enter` (interject) and `Shift+Enter` (newline).

31* VS Code, Cursor, Windsurf, and Zed terminals cannot distinguish `Shift+Enter` from `Enter`; use `Alt+Enter` for newlines. The same applies to VS Code over SSH.

32* Zellij intercepts many Ctrl chords. On Zellij 0.41+, switch to the "Unlock-First (non-colliding)" preset (`Ctrl+O` → `c` → Change Mode Behavior), then `Ctrl+G` temporarily unlocks Zellij when you need it.

33* Apple Terminal: `Ctrl+O` interjects (it lacks the Kitty keyboard protocol for `Ctrl+Enter`).

34 

35## No fullscreen, or mouse scrolling stops

36 

37Grok intentionally runs inline under Zellij and tmux control mode (`tmux -CC`); force fullscreen with `alt_screen = "always"` under `[terminal]` in `~/.grok/pager.toml`, or disable it anywhere with `--no-alt-screen`.

38 

39If your terminal's native scrollbar takes over, mouse reporting is off: Apple Terminal re-enables it under View → Allow Mouse Reporting (`Cmd+R`); iTerm2 under Settings → Profiles → Terminal → "Enable mouse reporting".

40 

41Still stuck? Run `/feedback`.

1#### Features

2 

3# Background Tasks

4 

5Grok can run commands, subagents, and monitors in the background while the conversation continues. Press `Ctrl+B` to open the tasks pane listing everything currently running, or run `/tasks` for a snapshot in the scrollback; press `Ctrl+G` to demote a running foreground command to the background instead of waiting for it.

6 

7## Background commands

8 

9The agent starts dev servers, builds, and other long-running commands as background tasks on its own, and collects their output when needed. Ask for it directly ("run the dev server in the background") or let the agent decide. In the scrollback, select a background task and press `x` to kill it.

10 

11## Scheduled prompts

12 

13`/loop` runs a prompt on a recurring interval:

14 

15```text

16/loop 5m Check if the test suite passes and report any failures

17```

18 

19The interval accepts `Ns` (minimum 60), `Nm`, `Nh`, and `Nd`. The prompt fires immediately, then repeats; each firing is a new agent turn. Loops expire after 7 days, and at most 50 scheduled tasks can be active at once. Cancel from the tasks pane, or ask the agent to.

20 

21## Monitors

22 

23For real-time event streams rather than periodic checks, the agent can attach a monitor to a script: each line the script prints becomes a notification in the conversation. Ask for one when you want to watch a log, a CI run, or a port ("watch the deploy logs and tell me if anything errors"). Keep monitor scripts selective — every output line interrupts the conversation.

24 

25## Prompt queue

26 

27Prompts submitted while a turn is running are queued, not dropped. `Ctrl+;` toggles the queue panel and `/queue` lists it.

1#### Features

2 

3# Agent Dashboard

4 

5The dashboard is a fullscreen overview of every session: which agents need input, which are working, and which are done. Open it with `Ctrl+\`, the `/dashboard` command, or `grok dashboard` from the shell.

6 

7Rows are grouped by state — Needs input, Working, Idle, Inactive, Completed, Failed — and update live. Press `Ctrl+G` to group by directory instead.

8 

9## Working with agents

10 

11Selecting a row opens a peek panel showing the agent's latest activity. Type to reply: an idle agent receives the message immediately, a busy one queues it. Permission prompts and questions can be answered inline with the number keys. Press `Enter` to attach to the session in a full details view; `Ctrl+\` returns to the dashboard, and `Ctrl+[` / `Ctrl+]` cycle between sessions.

12 

13The input bar at the bottom dispatches prompts to new sessions. `Ctrl+L` changes the working directory for new agents, and `Ctrl+W` toggles whether they start in a [git worktree](/build/features/worktrees).

14 

15## Keys

16 

17| Keys | Action |

18| ---- | ------ |

19| `↑`/`↓` | Select row |

20| `Enter` | Open the selected session |

21| `Ctrl+/` | Search — `a:<name>` by agent, `s:<state>` by state, or plain text |

22| `Ctrl+T` | Pin / unpin agent |

23| `Ctrl+R` | Rename agent |

24| `Ctrl+X` | Stop / close agent (press twice) |

25| `Shift+↑`/`Shift+↓` | Reorder pinned agents |

26| `Esc` | Close peek, then filter, then the dashboard |

27 

28Grouping and pins persist under `[dashboard]` in `~/.grok/config.toml`. Set `enabled = false` there, or `GROK_AGENT_DASHBOARD=0`, to disable the feature.

1#### Features

2 

3# Hooks

4 

5A hook is a shell command or HTTP endpoint that Grok calls when a lifecycle event occurs: block a dangerous command before it runs, log tool use, run a formatter after edits, or send a notification when a turn ends.

6 

7## Configuration

8 

9Hooks are JSON files. Personal hooks live in `~/.grok/hooks/*.json`; project hooks live in `<project>/.grok/hooks/*.json`. Claude Code (`.claude/settings.json`) and Cursor (`.cursor/hooks.json`) hook files are read as well, including Cursor's camelCase event names.

10 

11```json

12{

13 "hooks": {

14 "PreToolUse": [

15 {

16 "matcher": "Bash",

17 "hooks": [{ "type": "command", "command": "bin/safety-check.sh", "timeout": 10 }]

18 }

19 ]

20 }

21}

22```

23 

24`matcher` is a regular expression tested against the tool name (Claude tool names such as `Bash`, `Read`, and `Edit` are mapped to Grok's automatically); omit it to match everything. `type` is `"command"` or `"http"` (with a `url` to POST the event to). `timeout` is in seconds, default 5. Manage and inspect loaded hooks in the `/hooks` tab of the extensions modal.

25 

26Project hooks require trust before they run: the first time you open a repo with hooks, grant it with `/hooks-trust` or by launching with `--trust`. The decision is stored in `~/.grok/trusted_folders.toml` and covers project MCP and LSP servers too.

27 

28## Events

29 

30| Event | Fires when |

31| ----- | ---------- |

32| `SessionStart`, `SessionEnd` | A session starts or ends |

33| `UserPromptSubmit` | You submit a prompt |

34| `PreToolUse` | A tool is about to run — the only blocking event |

35| `PostToolUse`, `PostToolUseFailure` | A tool completes or fails |

36| `PermissionDenied` | The permission system denies a tool call |

37| `Stop`, `StopFailure` | A turn ends, or ends with an API error |

38| `Notification` | The agent sends a notification |

39| `SubagentStart`, `SubagentStop` | A subagent starts or finishes |

40| `PreCompact`, `PostCompact` | Conversation compaction runs |

41 

42## The script contract

43 

44The event arrives as JSON on stdin, including `hookEventName`, `sessionId`, `cwd`, `workspaceRoot`, and for tool events `toolName` and `toolInput`. Every hook process also receives `GROK_HOOK_EVENT`, `GROK_HOOK_NAME`, `GROK_SESSION_ID`, and `GROK_WORKSPACE_ROOT` in its environment.

45 

46A `PreToolUse` hook decides by writing JSON to stdout:

47 

48```json

49{ "decision": "deny", "reason": "Unsafe command detected" }

50```

51 

52Exit code 0 allows, exit code 2 denies. Everything else — timeouts, crashes, malformed output — is fail-open: the failure is recorded in the session but the tool call proceeds. Only an explicit `deny` blocks. For passive events, stdout is ignored; exit 0 on success.

1#### Features

2 

3# MCP Servers

4 

5MCP ([Model Context Protocol](https://modelcontextprotocol.io)) servers expose external tools to Grok. Once configured, their tools are available alongside the built-in ones, namespaced as `<server>__<tool>`.

6 

7## Adding a server

8 

9The fastest way is the `grok mcp` command:

10 

11```bash customLanguage="bash"

12# Local stdio server; everything after -- is the server command

13grok mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir

14 

15# Remote server over HTTP (OAuth handled automatically)

16grok mcp add --transport http linear https://mcp.linear.app/mcp

17 

18# Remote server with a static auth header (--header is repeatable)

19grok mcp add --transport http api https://mcp.example.com/mcp --header "Authorization: Bearer ${API_TOKEN}"

20```

21 

22`grok mcp list` shows configured servers, `grok mcp remove <name>` deletes one, and `grok mcp doctor [name]` diagnoses configuration and connectivity. `list` and `doctor` take `--json` for machine-readable output.

23 

24Servers can also be declared directly in `~/.grok/config.toml`:

25 

26```toml customLanguage="toml"

27[mcp_servers.filesystem]

28command = "npx"

29args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]

30env = { API_KEY = "${MY_API_KEY}" } # ${VAR} expands at load time

31startup_timeout_sec = 30 # default 30

32tool_timeout_sec = 6000 # default 6000

33 

34[mcp_servers.linear]

35url = "https://mcp.linear.app/mcp"

36headers = { "x-mcp-session-id" = "{{session_id}}" }

37```

38 

39Grok expands `${VAR}` (and `${VAR:-default}`) in `url`, `command`, `args`, `env`, and `headers`, so secrets can stay in the environment. Servers that require OAuth trigger a browser flow on first use; tokens are stored under `~/.grok/mcp_credentials.json`.

40 

41## Project scope

42 

43Pass `--scope project` to `grok mcp add` (it writes `.grok/config.toml` in the current directory) to define servers that ship with the repo. When loading, Grok walks from the current directory up to the git root reading each `.grok/config.toml`, and a project server with the same name as a user one replaces it entirely.

44 

45## In the TUI

46 

47`/mcps` opens the MCP tab of the extensions modal: toggle a server with `Space`, refresh after config edits with `r`, authenticate OAuth servers with `i`, and add or remove with `a` and `x`.

48 

49## Compatibility

50 

51Grok also loads MCP configurations from `~/.claude.json`, `.cursor/mcp.json`, and project `.mcp.json` files, merged below `config.toml` in priority. Disable a vendor with `[compat.claude] mcps = false` or `[compat.cursor] mcps = false`. `grok inspect` shows every loaded server and its origin.

52 

53## Troubleshooting

54 

55`grok mcp doctor` is the first stop. For stdio servers that start but fail to connect, Grok captures stderr to `~/.grok/logs/mcp/<server>.stderr.log`. Cold-start `npx` servers that download packages on first launch may need a higher `startup_timeout_sec`.

1#### Features

2 

3# AGENTS.md

4 

5Project rules are Markdown files that Grok loads into context for every session in a directory tree. Put coding conventions, build and test commands, and architecture notes in an `AGENTS.md` at your repo root, and Grok follows them without being told each session.

6 

7## Discovery

8 

9Grok loads rules in this order, with deeper files taking precedence on conflicts:

10 

111. Global rules in `~/.grok/`

122. Every directory from the repo root down to the working directory (or only the working directory outside a git repo)

13 

14Within each directory, Grok reads any of `AGENTS.md`, `Agents.md`, `AGENT.md`, `CLAUDE.md`, `Claude.md`, and `CLAUDE.local.md`, plus every `*.md` file in a `.grok/rules/` directory (`.claude/rules/` and `.cursor/rules/` are read for compatibility). Files ignored by `.gitignore` are skipped, which keeps personal overrides like `CLAUDE.local.md` out of shared context.

15 

16A nested `AGENTS.md` scopes to its subtree, so a monorepo can carry different conventions per package:

17 

18```text

19my-monorepo/

20 AGENTS.md # repo-wide rules

21 packages/

22 frontend/AGENTS.md # "Use React. Prefer CSS modules."

23 backend/AGENTS.md # "Use Express. Follow REST conventions."

24```

25 

26Files are loaded in full, with no size cap; short, specific instructions are followed more reliably than long ones.

27 

28## Session rules

29 

30To add rules for a single run without editing files, pass `--rules` (Grok appends the text to the system prompt), or `--system-prompt-override` to replace the system prompt entirely:

31 

32```bash customLanguage="bash"

33grok --rules "Always use TypeScript. Prefer functional components."

34```

35 

36## Verification

37 

38```bash customLanguage="bash"

39grok inspect

40```

41 

42This lists each rules file Grok found, with its path and approximate token count.

1#### Features

2 

3# Sessions

4 

5Grok saves every conversation to disk automatically — prompts, responses, tool calls, and file snapshots — under `~/.grok/sessions/`, keyed by working directory. Sessions work the same in the TUI, headless mode, and over ACP.

6 

7## Resuming

8 

9In the TUI, `/resume` opens a picker of recent sessions for the current workspace; the welcome screen lists them too. From the command line:

10 

11```bash customLanguage="bash"

12grok --resume <session-id> # a specific session

13grok --resume # the most recent for this directory

14grok -c # shorthand: continue the most recent

15```

16 

17In headless mode, read the session ID back from JSON output and pass it to `-r` to build multi-step automations:

18 

19```bash customLanguage="bash"

20grok -p "Start the refactor" --output-format json | jq -r '.sessionId'

21```

22 

23`-s, --session-id` names a new session with a UUID you supply; it does not resume existing ones. To branch a resumed session instead of continuing it, add `--fork-session`.

24 

25## Forking

26 

27`/fork [directive]` branches the current session into a peer that starts from a copy of the conversation. Pass `--worktree` or `--no-worktree` to choose whether the fork runs in an isolated copy of the repository, so parallel sessions do not overwrite each other's files — see [Worktrees](/build/features/worktrees).

28 

29## Rewinding

30 

31`/rewind` (or `Esc Esc` while idle) lists a rewind point per prompt. Selecting one restores all files to their state at that point and truncates the conversation to match. Rewind modifies files on disk — reverted changes are lost unless committed to git.

32 

33## Compacting

34 

35`/compact [context]` compresses the conversation history to reclaim context window, with optional instructions about what to preserve. Grok also auto-compacts as the context window fills; check usage with `/context` or `/session-info`.

36 

37## Housekeeping

38 

39| Command | What it does |

40| ------- | ------------ |

41| `/sessions` | Switch, rename, or close active sessions |

42| `/rename <title>` | Rename the current session (alias `/title`) |

43| `grok sessions list` | List recent sessions for this directory |

44| `grok sessions search <query>` | Search session titles and prompts |

45| `grok sessions delete <id>` | Permanently delete a session |

46| `grok export <id> [file]` | Export a transcript as Markdown (`--clipboard` to copy) |

39* Project `.grok/hooks/` (requires `/hooks-trust`)39* Project `.grok/hooks/` (requires `/hooks-trust`)

40* Enabled plugins40* Enabled plugins

41 41 

42All hooks receive `GROK_HOOK_EVENT`, `GROK_HOOK_NAME`, `GROK_SESSION_ID`, and `GROK_WORKSPACE_ROOT`. Plugin hooks also receive `GROK_PLUGIN_ROOT` and `GROK_PLUGIN_DATA`. Runner and plugin values take precedence over any `env` declared in the hook definition. See the in-app Hooks guide for expansion rules and full details.42Plugin hooks additionally receive `GROK_PLUGIN_ROOT` and `GROK_PLUGIN_DATA` in their environment. For events, the JSON format, and the script contract, see [Hooks](/build/features/hooks).

43 43 

44## Marketplaces44## Marketplaces

45 45 

59 59 

60## Agents.md compatibility60## Agents.md compatibility

61 61 

62Grok also reads the `AGENTS.md` instruction-file family (`AGENTS.md`, `Agents.md`, `AGENT.md`) walked from cwd to the repo root, and discovers user-level skills and commands from:62Grok also reads the `AGENTS.md` instruction-file family (`AGENTS.md`, `Agents.md`, `AGENT.md`) walked from cwd to the repo root — see [AGENTS.md](/build/features/project-rules) — and discovers user-level skills and commands from:

63 63 

64* `~/.agents/skills/`64* `~/.agents/skills/`

65* `~/.agents/commands/`65* `~/.agents/commands/`

1#### Features

2 

3# Theming

4 

5Run `/theme` (alias `/t`) to open the theme picker with a live preview, `/theme <name>` to switch directly, or set it in `~/.grok/config.toml`:

6 

7```toml customLanguage="toml"

8[ui]

9theme = "tokyonight"

10```

11 

12## Built-in themes

13 

14| Theme | Names | Truecolor required |

15| ----- | ----- | ------------------ |

16| GrokNight (default) | `groknight`, `dark` | No |

17| GrokDay | `grokday`, `light`, `day` | No |

18| TokyoNight | `tokyonight`, `tokyo` | Yes |

19| RosePineMoon | `rosepine`, `rose-pine-moon` | Yes |

20| OscuraMidnight | `oscura`, `oscura-midnight` | Yes |

21 

22On terminals without truecolor, themes are quantized to the available palette and the picker hides the truecolor-only entries. If colors look wrong, see [Terminal Support](/build/cli/terminal-support).

23 

24## Following the system appearance

25 

26Set `theme = "auto"` (alias `"system"`) to track your OS light/dark setting; changes apply within seconds, without a restart. Dark maps to GrokNight and light to GrokDay unless overridden:

27 

28```toml customLanguage="toml"

29[ui]

30theme = "auto"

31auto_dark_theme = "tokyonight"

32auto_light_theme = "grokday"

33```

34 

35For a denser layout, `/compact-mode` reduces padding and persists the choice. Finer appearance controls (scrollback layout, block styling, animations) live in `~/.grok/pager.toml`.

1#### Features

2 

3# Worktrees

4 

5A worktree session runs in an isolated copy of your repository, so parallel agents cannot overwrite each other's files. Worktrees require a git repository, live under `~/.grok/worktrees/<repo>/<name>`, and start from your current HEAD, including uncommitted changes.

6 

7## Starting one

8 

9```bash customLanguage="bash"

10grok -w

11grok --worktree=feat "refactor module X" # = keeps the prompt out of the name

12grok -w --ref main "fix the flaky test" # clean checkout of the ref

13grok -w -r <session-id> # resume in a fresh worktree

14```

15 

16In the TUI: `/fork --worktree` forks the current session into a worktree, `Ctrl+W` on the welcome screen opens the New Worktree dialog, and `Ctrl+W` in the [Agent Dashboard](/build/features/dashboard) dispatches new agents into worktrees. Whether `/new` and `/fork` offer a worktree is configurable — see [TOML Values](/build/settings/reference#toml-values).

17 

18A worktree is a real git checkout, detached at its base commit; land changes with ordinary git.

19 

20## Housekeeping

21 

22Worktrees persist until you remove them: ending or deleting a session leaves its worktree in place, and `gc` runs only when you invoke it.

23 

24| Command | What it does |

25| ------- | ------------ |

26| `grok worktree list` | List tracked worktrees |

27| `grok worktree show <id>` | Show details for one worktree |

28| `grok worktree rm <ids...>` | Remove worktrees (`--dry-run` to preview) |

29| `grok worktree gc` | Remove entries whose directory is gone; `--max-age 7d` also expires idle worktrees not in use by a running process |

1# Keyboard Shortcuts

2 

3Press `Ctrl+.` (or `Ctrl+X` on Windows and in terminals without the Kitty keyboard protocol) to open this list inside the TUI; entries that do not apply in the current context are dimmed.

4 

5Some chords differ by terminal; see [Terminal differences](#terminal-differences).

6 

7## Essentials

8 

9| Keys | Action |

10| ---- | ------ |

11| `Enter` | Send the prompt |

12| `Tab` | Move focus between prompt and scrollback |

13| `Esc` | Cancel the running turn |

14| `Esc Esc` | Clear the prompt, or open rewind when it is empty |

15| `Ctrl+C` | Cancel turn |

16| `Shift+Tab` | Cycle mode (Normal / Plan / Always-approve) |

17| `Ctrl+P` or `?` | Command palette |

18| `Ctrl+.` / `Ctrl+X` | Keyboard shortcuts |

19| `F2` or `Ctrl+,` | Settings |

20| `Ctrl+Q` / `Ctrl+D` | Quit (press twice) |

21 

22## Input

23 

24| Keys | Action |

25| ---- | ------ |

26| `Ctrl+Enter` or `Ctrl+I` | Interject while a turn is running |

27| `Shift+Enter` | Newline — or send, in multiline mode (`Alt+Enter` where `Shift+Enter` is unsupported) |

28| `Ctrl+M` | Toggle multiline input |

29| `Ctrl+R` | Search prompt history |

30| `!` | Shell mode, on an empty prompt |

31 

32## Scrollback

33 

34Focus the scrollback with `Tab`, then navigate. Bare-letter keys require vim mode (`/vim-mode`, or `vim_mode = true` under `[ui]` in `config.toml`); the arrow-key equivalents always work.

35 

36| Keys | Action |

37| ---- | ------ |

38| `j` / `↓`, `k` / `↑` | Select next / previous entry |

39| `Shift+L` / `Shift+→`, `Shift+H` / `Shift+←` | Next / previous turn |

40| `Shift+J`, `Shift+K` | Next / previous response |

41| `g`, `Shift+G` | Go to top / bottom |

42| `Ctrl+U`, `Ctrl+D` | Scroll half page up / down |

43| `Page Up`, `Page Down` | Scroll one page up / down |

44| `h` / `←`, `l` / `→` | Collapse / expand the selected entry |

45| `e`, `Shift+E` | Expand or collapse one entry / all entries |

46| `Ctrl+E` | Toggle all thinking blocks |

47| `r` | Toggle raw markdown |

48| `y`, `Shift+Y` | Copy content / copy command or path |

49| `Enter` or `Ctrl+F` | Open the selected block in the fullscreen viewer |

50| `/` | Search scrollback (vim mode) |

51| `x` | Kill the selected background task |

52 

53## Panels and session

54 

55| Keys | Action |

56| ---- | ------ |

57| `Ctrl+T` | Toggle todo pane |

58| `Ctrl+B` | Toggle tasks pane |

59| `Ctrl+;` or `Ctrl+'` | Toggle prompt queue |

60| `Ctrl+S` | Open sessions |

61| `Ctrl+L` | Open extensions |

62| `Ctrl+G` | Send the running command to the background |

63| `Ctrl+O` | Toggle always-approve |

64| `Ctrl+N` | New session (press twice) |

65| `Ctrl+M` | Pick model, when the prompt is not focused |

66| `Ctrl+\` | Open the [Agent Dashboard](/build/features/dashboard) |

67 

68## Terminal differences

69 

70* VS Code-family terminals (VS Code, Cursor, Windsurf, Zed): quit is `Ctrl+D` only, interject is `Ctrl+L`, half-page scroll is `Shift+D`, and `Ctrl+L` does not open extensions (use `/plugins`). Use `Alt+Enter` for newlines.

71* Apple Terminal: `Ctrl+O` also interjects.

72* WezTerm needs `enable_kitty_keyboard = true` for `Ctrl+Enter` and `Shift+Enter`.

73 

74See [Terminal Support](/build/cli/terminal-support) for fixes and diagnostics.

2 2 

3The TUI has pager-local slash commands, plus a smaller set provided by `xai-grok-shell`. User-invocable skills also appear as slash commands.3The TUI has pager-local slash commands, plus a smaller set provided by `xai-grok-shell`. User-invocable skills also appear as slash commands.

4 4 

5In the TUI, `Shift+Tab` cycles session modes.5In the TUI, `Shift+Tab` cycles session modes. For the full key reference, see [Keyboard Shortcuts](/build/keyboard-shortcuts).

6 6 

7## Modes7## Modes

8 8 

9### Plan9### Plan

10 10 

11Plan mode is for planning first. When it is active, write tools are blocked except for the session plan file.11Plan mode is for planning first. When it is active, edits to the session plan file are auto-approved while writes to other files still require your approval.

12 12 

13Use it when you want Grok to sketch the approach before it starts making changes. Use `/plan` to view the current session plan.13Use it when you want Grok to sketch the approach before it starts making changes. Enter it with `/plan [description]` and view the current plan with `/view-plan`.

14 14 

15Plan mode keeps the working plan visible in the TUI.15Plan mode keeps the working plan visible in the TUI.

16 16 

52| Command | What it does |52| Command | What it does |

53| ------- | ------------ |53| ------- | ------------ |

54| `/quit` (alias `/exit`) | Quit the application |54| `/quit` (alias `/exit`) | Quit the application |

55| `/help` | Browse commands and keyboard shortcuts |

55| `/home` | Return to the welcome screen |56| `/home` | Return to the welcome screen |

56| `/new` | Start a new session |57| `/new` (alias `/clear`) | Start a new session |

57| `/resume` | Resume a previous session |58| `/resume` | Resume a previous session |

58| `/sessions` | Browse and pick from past sessions |59| `/sessions` | Switch, rename, or close active sessions |

59| `/fork` | Fork the current session into a new one |60| `/fork` | Branch the current session into a peer agent |

60| `/rename <title>` | Rename the current session |61| `/rename <title>` (alias `/title`) | Rename the current session |

61| `/share` | Share the current session via URL |62| `/share` | Share the current session via URL |

62| `/session-info` | Show session info |63| `/session-info` | Show session info |

63| `/context` | View context usage |64| `/context` | View context usage |

64| `/model <name>` | Switch the active model |

65| `/always-approve` | Toggle always-approve mode |

66| `/multiline` | Toggle multiline input |

67| `/compact [context]` | Compact conversation history |65| `/compact [context]` | Compact conversation history |

66| `/rewind` | Rewind to a previous turn |

67| `/export` | Export the conversation to a file or clipboard |

68| `/copy [N]` | Copy the last (or Nth-latest) response to the clipboard |

69| `/find` | Search the conversation scrollback |

70| `/transcript` | View the full transcript in your pager (`$PAGER`) |

71| `/model <name>` (alias `/m`) | Switch the active model |

72| `/effort` | Set reasoning effort for the current model |

73| `/always-approve` | Toggle always-approve mode |

74| `/plan [description]` | Enter plan mode |

75| `/view-plan` | View the current plan |

76| `/btw <question>` | Ask a side question without interrupting |

77| `/loop [interval] <prompt>` | Run a prompt on a recurring interval — see [Background Tasks](/build/features/background-tasks) |

78| `/imagine <prompt>` | Generate an image from a text description |

79| `/imagine-video <prompt>` | Generate a video from a text description |

80| `/tasks` | List background tasks, subagents, and scheduled tasks |

81| `/queue` | List the prompts queued behind the running turn |

82| `/dashboard` | Open the [Agent Dashboard](/build/features/dashboard) |

83| `/settings` (alias `/config`) | Open the settings modal |

84| `/theme [name]` (alias `/t`) | Switch the color theme |

68| `/compact-mode` | Toggle denser UI layout |85| `/compact-mode` | Toggle denser UI layout |

69| `/theme [name]` | Switch the color theme |86| `/multiline` (alias `/ml`) | Toggle multiline input |

87| `/vim-mode` | Toggle vim-style scrollback keybindings |

88| `/timestamps` | Toggle message timestamps |

89| `/terminal-setup` | Check terminal and clipboard setup |

90| `/config-agents` (alias `/agents`) | Manage agent definitions |

91| `/personas` | Manage personas |

92| `/remember <note>` | Save a memory note |

93| `/import-claude` | Open the Claude settings import modal |

70| `/feedback [text]` | Send feedback about the current session |94| `/feedback [text]` | Send feedback about the current session |

71| `/plan` | View the current session plan |95| `/release-notes` (alias `/changelog`) | View release notes for the current version |

72| `/btw <question>` | Ask a side question without interrupting |96| `/usage` | View credit usage or manage billing |

73| `/rewind` | Rewind to an earlier point in the conversation |97| `/privacy` | Show or toggle privacy and data-retention status |

74| `/usage` | Show token and credit usage for the session |98| `/login`, `/logout` | Sign in, or sign out of the current account |

75| `/logout` | Sign out of the current account |

76| `/hooks` | Open the unified extensions modal at the Hooks tab |99| `/hooks` | Open the unified extensions modal at the Hooks tab |

77| `/plugins` | Open the unified extensions modal at the Plugins tab |100| `/plugins` | Open the unified extensions modal at the Plugins tab |

101| `/marketplace` | Open the unified extensions modal at the Marketplace tab |

78| `/skills` | Open the unified extensions modal at the Skills tab |102| `/skills` | Open the unified extensions modal at the Skills tab |

79| `/mcps` | Open the unified extensions modal at the MCP tab |103| `/mcps` | Open the unified extensions modal at the MCP tab |

80 104 

81`/hooks`, `/plugins`, `/skills`, and `/mcps` all open the same extensions modal — they just pre-select a tab.105`/hooks`, `/plugins`, `/marketplace`, `/skills`, and `/mcps` all open the same extensions modal — they just pre-select a tab. A few commands appear only when their feature is available (for example `/imagine` and `/loop`).

82 106 

83## Shell-provided commands107## Shell-provided commands

84 108 

85| Command | What it does |109| Command | What it does |

86| ------- | ------------ |110| ------- | ------------ |

87| `/flush` | Flush conversation memory to disk now |111| `/flush` | Flush conversation memory to disk now |

88| `/memory` | Search and edit persistent memory entries |112| `/memory` (alias `/mem`) | Browse, view, and manage your memories |

89| `/dream` | Trigger an offline memory-consolidation pass |113| `/dream` | Run memory consolidation |

90| `/imagine <prompt>` | Generate an image from text |114 

91| `/imagine-video <prompt>` | Generate a video from text |115These appear when cross-session memory is enabled.

92 116 

93## Skills as commands117## Skills as commands

94 118 

1# Getting Started1#### Getting Started

2 

3# Grok Build

2 4 

3Grok Build is a powerful and extensible coding agent. Use it via an interactive TUI, headlessly in scripts or bots, or through the Agent Client Protocol (ACP) in other apps.5Grok Build is a powerful and extensible coding agent. Use it via an interactive TUI, headlessly in scripts or bots, or through the Agent Client Protocol (ACP) in other apps.

4 6 

78 -H "Content-Type: application/json" \80 -H "Content-Type: application/json" \

79 -d '{81 -d '{

80 "model": "grok-build-0.1",82 "model": "grok-build-0.1",

81 "input": "Refactor this function to handle null inputs."83 "input": "Fix this function and explain the bug: function median(a){a.sort();return a[a.length/2]}"

82 }'84 }'

83```85```

84 86 

90client = Client(api_key=os.getenv("XAI_API_KEY"))92client = Client(api_key=os.getenv("XAI_API_KEY"))

91 93 

92chat = client.chat.create(model="grok-build-0.1")94chat = client.chat.create(model="grok-build-0.1")

93chat.append(user("Refactor this function to handle null inputs."))95chat.append(user("Fix this function and explain the bug: function median(a){a.sort();return a[a.length/2]}"))

94 96 

95print(chat.sample().content)97print(chat.sample().content)

96```98```

105 107 

106response = client.responses.create(108response = client.responses.create(

107 model="grok-build-0.1",109 model="grok-build-0.1",

108 input="Refactor this function to handle null inputs.",110 input="Fix this function and explain the bug: function median(a){a.sort();return a[a.length/2]}",

109)111)

110 112 

111print(response.output_text)113print(response.output_text)

117 119 

118const { text } = await generateText({120const { text } = await generateText({

119 model: xai.responses('grok-build-0.1'),121 model: xai.responses('grok-build-0.1'),

120 prompt: 'Refactor this function to handle null inputs.',122 prompt: 'Fix this function and explain the bug: function median(a){a.sort();return a[a.length/2]}',

121});123});

122 124 

123console.log(text);125console.log(text);

4 4 

5Settings are persisted under `~/.grok/config.toml` (on Windows, `%USERPROFILE%\.grok\config.toml`). To configure the default home directory, you can set `$GROK_HOME`.5Settings are persisted under `~/.grok/config.toml` (on Windows, `%USERPROFILE%\.grok\config.toml`). To configure the default home directory, you can set `$GROK_HOME`.

6 6 

7For MCP servers, marketplaces, skills, plugins, and hooks, see [Skills, Plugins, and Marketplaces](/build/features/skills-plugins-marketplaces).7For MCP servers, see [MCP Servers](/build/features/mcp-servers). For marketplaces, skills, and plugins, see [Skills, Plugins, and Marketplaces](/build/features/skills-plugins-marketplaces); for hooks, see [Hooks](/build/features/hooks).

8 8 

9## Scopes9## Scopes

10 10 

16| Managed | `~/.grok/managed_config.toml`, `/etc/grok/managed_config.toml` | Enterprise-served defaults |16| Managed | `~/.grok/managed_config.toml`, `/etc/grok/managed_config.toml` | Enterprise-served defaults |

17| Requirements | `~/.grok/requirements.toml`, `/etc/grok/requirements.toml` | Policy pins |17| Requirements | `~/.grok/requirements.toml`, `/etc/grok/requirements.toml` | Policy pins |

18 18 

19Project configs are limited to MCP servers, plugins, and permission rules, not full user configs. For more on scope merge order, sandoxing, and managed deployments, see [Enterprise Deployment](/build/enterprise).19Project configs are limited to MCP servers, plugins, and permission rules, not full user configs. For scope merge order and managed deployments, see [Enterprise Deployments](/build/enterprise#configuration). [Permission rules](/build/enterprise#permissions) and [sandboxing](/build/enterprise#sandbox) are documented there too — they apply to individual use as much as to fleets.

20 20 

21## Verification21## Verification

22 22 

183 183 

184A non-empty `deny` list is enforced at the kernel level when the sandbox can be applied. On Linux, read-deny requires `bubblewrap`. For managed deployments and policy, see [Enterprise Deployment](/build/enterprise).184A non-empty `deny` list is enforced at the kernel level when the sandbox can be applied. On Linux, read-deny requires `bubblewrap`. For managed deployments and policy, see [Enterprise Deployment](/build/enterprise).

185 185 

186### `[session]` and `[cli]`186### `[session]`, `[cli]`, and `[hints]`

187 187 

188| Setting | Section | Values / default | Description |188| Setting | Section | Values / default | Description |

189| --- | --- | --- | --- |189| --- | --- | --- | --- |

192| `auto_update` | `[cli]` | `true` / `false` (default on when unset) | Check for CLI updates on launch. |192| `auto_update` | `[cli]` | `true` / `false` (default on when unset) | Check for CLI updates on launch. |

193| `channel` | `[cli]` | `stable` | `alpha` | Release channel preference. |193| `channel` | `[cli]` | `stable` | `alpha` | Release channel preference. |

194| `show_tips` | `[cli]` | `true` / `false` | Startup tips. |194| `show_tips` | `[cli]` | `true` / `false` | Startup tips. |

195| `new_session_worktree_mode` | `[hints]` | `ask` | `always` | `never` (default `never`) | Whether `/new` offers a [worktree](/build/features/worktrees). |

196| `fork_worktree_mode` | `[hints]` | `ask` | `always` | `never` (default `ask`) | Whether `/fork` offers a worktree. |

195 197 

196### `[permission]`198### `[permission]`

197 199