# Configure Grok

> How to set config.toml and pager.toml, precedence (CLI > env > user config > managed/requirements > defaults), feature flags, and grok inspect to dump resolved settings.

- 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/05-configuration.md`
- `crates/codegen/xai-grok-config/src/loader.rs`
- `crates/codegen/xai-grok-config/src/paths.rs`
- `crates/codegen/xai-grok-shell/src/util/config/load.rs`
- `crates/codegen/xai-grok-shell/src/util/config/resolve/mod.rs`
- `crates/codegen/xai-grok-shell/src/inspect/mod.rs`
- `crates/codegen/xai-grok-paths/src/lib.rs`

---

---
title: "Configure Grok"
description: "How to set config.toml and pager.toml, precedence (CLI > env > user config > managed/requirements > defaults), feature flags, and grok inspect to dump resolved settings."
---

Grok resolves runtime settings by deep-merging layered TOML (`managed_config.toml`, user `config.toml`, `requirements.toml`, optional macOS MDM) under `$GROK_HOME` (default `~/.grok`) or `/etc/grok`, then applying environment variables and CLI flags on top. Appearance and TUI layout live mainly in `pager.toml`; agent behavior, models, tools, features, and MCP live in `config.toml`. Missing files yield empty tables and built-in defaults—only override what you need.

## Config home and file map

| Path | Role |
|------|------|
| `$GROK_HOME` or `~/.grok` | User config root (`GROK_HOME` overrides home) |
| `~/.grok/config.toml` | Primary user settings |
| `~/.grok/pager.toml` | TUI appearance / layout |
| `~/.grok/managed_config.toml` | User-tier managed policy (org/sync) |
| `~/.grok/requirements.toml` | Requirements / policy pin (often signed cloud cache) |
| `/etc/grok/managed_config.toml` | System managed (Unix) |
| `/etc/grok/requirements.toml` | System requirements (Unix) |
| `.grok/config.toml` | Project MCP, plugins, `[permission]`, some tool caps |
| macOS MDM `ai.x.grok` (`requirements_toml_base64`) | Highest requirements tier when admin-forced |

On Unix, system config is `/etc/grok`. On Windows there is no system dir. Loaders never promote a cwd-relative `.grok/` to the **user** tier when no home resolves—project files stay project-scoped.

String values support `$VAR` / `${VAR}` expansion at load time.

## Precedence

### Operator-facing order (highest first)

1. **CLI flags** — e.g. `--model`, `--sandbox`, `--yolo`, `--minimal` / `--fullscreen`
2. **Environment variables** — e.g. `XAI_API_KEY`, `GROK_MEMORY`, `GROK_TELEMETRY_ENABLED`
3. **User `config.toml`** — `$GROK_HOME/config.toml`
4. **Managed / requirements** — `managed_config.toml` and `requirements.toml` (system + user + MDM)
5. **Built-in defaults**

Use this mental model for day-to-day overrides. A few knobs invert managed vs user so org policy cannot be re-armed from user TOML (see feature flags below).

### Disk layer merge (lowest → highest)

Effective base config merges:

1. `/etc/grok/managed_config.toml` (system managed)
2. `$GROK_HOME/managed_config.toml` (user managed)
3. `$GROK_HOME/config.toml` (user)
4. `$GROK_HOME/requirements.toml`
5. `/etc/grok/requirements.toml`
6. macOS MDM requirements (when present)

Each layer may apply `[[version_overrides]]` before merge. Campaign patches can overlay fields after the base merge; requirements are re-applied so admin pins beat campaigns. The shell’s full path (`load_effective_config`) also honors remote campaign cache and `GROK_CAMPAIGNS_OVERRIDE`; one-shot CLI paths may use disk-only resolution.

### Project vs global

| Surface | Rule |
|---------|------|
| `[mcp_servers]`, `[plugins]` | Nearest project `.grok/config.toml` wins by name (full replace, not deep merge) over repo-root then user global |
| `[permission]` | Project sections override global wholesale for the chosen file; rule evaluation still merges deny > ask > allow across sources |
| Most other sections | Loaded only from effective global layers (`~/.grok/config.toml` + managed/requirements), not project files |

## `config.toml` (behavior)

Location: `~/.grok/config.toml`.

```toml
[cli]
auto_update = true

[models]
default = "grok-build"
web_search = "grok-4.20-multi-agent"
temperature = 0.7
top_p = 0.95
max_completion_tokens = 8192
max_retries = 8
stream_tool_calls = true

[ui]
simple_mode = true              # prompt editor: true = readline, false = vim-style
vim_mode = false                # scrollback vim keys (independent of simple_mode)
screen_mode = "fullscreen"      # sticky "minimal" | "fullscreen"; CLI flags rewrite this
theme = "auto"                  # or groknight, tokyonight, etc. (see Theming)
remember_tool_approvals = false
show_thinking_blocks = true
group_tool_verbs = true
default_selected_permission = "always_allow_all_sessions"

[features]
telemetry = false
feedback = true
lsp_tools = false
codebase_indexing = true
two_pass_compaction = false
remote_fetch = true             # model catalog / remote settings; air-gap: set false
# managed_config = true         # separate gate for background managed-config sync

[session]
auto_compact_threshold_percent = 85
load_envrc = true

[tools]
respect_gitignore = false
```

### Common sections

| Section | Purpose |
|---------|---------|
| `[cli]` | Auto-update and launch behavior |
| `[models]` / `[model.<id>]` | Default model, sampling, BYOK / OpenAI-compatible endpoints |
| `[ui]` | Prompt/scrollback UX, theme, sticky screen mode, notifications, scroll speed |
| `[features]` | Product feature toggles (telemetry, LSP tool, indexing, remote fetch, …) |
| `[session]` | Compact threshold, `.envrc` loading |
| `[tools]` | Cross-tool defaults (e.g. gitignore respect) |
| `[toolset.*]` | Per-tool timeouts and limits (`bash`, `ask_user_question`, `web_fetch`, …) |
| `[mcp_servers.<name>]` | MCP stdio/HTTP servers |
| `[skills]`, `[plugins]`, `[subagents]`, `[memory]` | Discovery paths, disables, routing |
| `[compat.cursor\|claude\|codex]` | Vendor skill/rule/MCP/hooks discovery cells (default on; env > TOML > default) |
| `[auth]`, `[grok_com_config]` | Auth provider binary, OIDC, enterprise login pins |
| `[permission]` | Allow/deny/ask rules (also project `.grok/config.toml`) |
| `[hints]` | Persisted “don’t ask again” UI prefs (TUI writes user file only) |
| `[telemetry]` | Collector redirects and optional external OTLP |

Credential resolution for models: `api_key` > `env_key` > signed-in session > `XAI_API_KEY`.

### Env overrides (selected)

| Variable | Effect |
|----------|--------|
| `GROK_HOME` | Config directory root |
| `XAI_API_KEY` | API key for CI/headless |
| `GROK_MEMORY` | `1`/`0` cross-session memory |
| `GROK_SUBAGENTS` | Enable/disable subagents |
| `GROK_WEB_FETCH` | Enable/disable `web_fetch` |
| `GROK_SANDBOX` | Sandbox profile name |
| `GROK_TELEMETRY_ENABLED` / `GROK_FEEDBACK_ENABLED` | Telemetry / feedback |
| `GROK_RESPECT_GITIGNORE` | Force `[tools] respect_gitignore` |
| `GROK_DEFAULT_SELECTED_PERMISSION` | First approval-menu cursor row |
| `GROK_SCROLL_SPEED`, `GROK_SCROLL_MODE`, `GROK_SCROLL_LINES`, `GROK_INVERT_SCROLL` | Scroll UX (load-time) |
| `GROK_CAMPAIGNS` | `0`/`false` disables campaign overlays |
| `GROK_DISABLE_API_KEY_AUTH` | Enterprise login hardening |

Env bool parsing accepts `1/true/yes/on/enabled` and `0/false/no/off/disabled`.

## Feature flags (`[features]`)

Feature keys are TOML booleans under `[features]`, often mirrored by `GROK_*` env vars. Important behaviors:

| Flag | Default (typical) | Notes |
|------|-------------------|-------|
| `telemetry` | off/on per build docs | Master anonymous usage telemetry |
| `feedback` | `true` | `/feedback` and related UI |
| `lsp_tools` | `false` | Expose the `lsp` tool |
| `codebase_indexing` | `true` | Code-graph indexing |
| `two_pass_compaction` | `false` | Opt-in two-pass compact |
| `remote_fetch` | `true` | Online model catalog + remote settings; **no env re-arm**; managed/requirements beat user for air-gapped pins |
| `managed_config` | (sync gate) | Background managed-config sync, independent of `remote_fetch` |
| `campaigns` | on unless disabled | Also killable with `GROK_CAMPAIGNS=0` |

**Policy knobs** such as `remote_fetch` walk layers as requirements (MDM > system > user) → managed → system managed → user, so a managed/requirements `false` cannot be undone by a user `true`. Ordinary effective merge still puts user over managed for preference fields.

`[compat.*]` cells use **env > config.toml > default (on)** and are reported by `grok inspect`.

## `pager.toml` (appearance)

Location: `~/.grok/pager.toml` (`$GROK_HOME/pager.toml`).

Controls TUI layout and chrome. Theme **names** primarily live under `config.toml` `[ui] theme` (and `/theme`); `pager.toml` owns terminal mode, animation, prompt chrome, scrollback geometry, and per-block styling. Changes apply on restart (dev builds may hot-reload `pager.toml`).

```toml
[terminal]
alt_screen = "auto"           # auto | always | never

[animation]
fps = 30
wave_rows = 32

[prompt]
collapse_unfocused = true
mouse_hover = true
show_prefix = true

[scrollback.layout]
outer_vpad = 1
outer_hpad_left = 2
outer_hpad_right = 2

[scrollback.scrollbar]
enabled = true

[scrollback.scroll]
follow_indicator = "center"
follow_auto_select = true
respect_manual_folds = false  # opt-in pin for manual folds

[scrollback.display]
sticky_headers = true
tab_width = 4

[scrollback.blocks.edit]
# expanded_by_default / line_summary: unset follows [ui] collapsed_edit_blocks
indent = true

[scrollback.blocks.thinking]
animate = true
truncate_lines = 3

[todo]
badge_format = "default"      # default | colon | comma

disable_plugins = false
```

**Screen mode interaction:** `[ui] screen_mode` in `config.toml` is the sticky fullscreen/minimal preference written by `--minimal` / `--fullscreen` and `/minimal` / `/fullscreen`. It outranks legacy `[terminal] minimal` in `pager.toml`. Explicit CLI flags win for that process and update the sticky key.

For color themes and truecolor constraints, see [Theming](/theming).

## `grok inspect` — dump resolved discovery

```bash
grok inspect
grok inspect --json
```

One-shot introspection of **cwd** (not a live session). Builds an `InspectReport` with:

- Version / channel / cwd / git project root
- **Folder trust** — when untrusted, project hooks, plugins, and project MCP/LSP are gated like runtime
- Project instructions (`AGENTS.md` and vendor peers) with scope and approx tokens
- Permissions sources, skipped rules, managed-settings path/active flags, enforced policies
- Login policy (`disable_api_key_auth`, forced team UUID)
- Hooks, skills, agents, plugins, marketplaces, MCP, LSP
- **`config_sources.layers`** — each contributing layer with role and path
- External compat cell resolution
- Model-override parse warnings

Layer roles reported:

| Role | Source |
|------|--------|
| `system-managed` | `/etc/grok/managed_config.toml` |
| `managed` | `$GROK_HOME/managed_config.toml` |
| `user` | `$GROK_HOME/config.toml` |
| `requirements` | `$GROK_HOME/requirements.toml` |
| `system-requirements` | `/etc/grok/requirements.toml` |
| `mdm` | macOS forced preferences (synthetic path label) |
| `project` | Ancestor `.grok/config.toml` files |

Layers that exist but contribute nothing after load processing get a `note` (`empty` or parse error). Use `--json` for machine-readable camelCase fields in CI or support bundles.

`grok inspect` does **not** print the fully merged TOML blob of every key; it dumps discovery surfaces and which config files participate. For key-level schema, see the configuration reference.

## Project-scoped files (quick map)

| Path | Contributes |
|------|-------------|
| `.grok/config.toml` | MCP, plugins, permission rules, limited tool caps |
| `.grok/skills/`, `.grok/hooks/`, `.grok/agents/`, `.grok/plugins/` | Local discovery |
| `.grok/lsp.json` / `~/.grok/lsp.json` | LSP servers |
| `.grok/sandbox.toml` | Custom sandbox profiles |
| `AGENTS.md` | Project instructions (system prompt) |

## Minimal workflow

1. Create or edit `~/.grok/config.toml` with only the sections you need.
2. Optionally tune `~/.grok/pager.toml` for scrollback/terminal chrome.
3. Prefer env vars for CI-safe overrides that must not rewrite disk config.
4. Run `grok inspect` (and `--json` if scripting) from the project directory to verify trust, layers, MCP, skills, and permissions.
5. For org pins, deploy `managed_config.toml` / `requirements.toml` under `/etc/grok` or MDM rather than relying on user files alone.

## Related pages

<CardGroup cols={2}>
  <Card title="Configuration reference" href="/configuration-reference">
    Schema-oriented keys for config.toml and pager.toml sections and env counterparts.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Top-level commands including inspect, setup, and shared runtime flags.
  </Card>
  <Card title="Theming" href="/theming">
    Theme names, /theme, color support, and screen modes.
  </Card>
  <Card title="Permissions and safety" href="/permissions-and-safety">
    Allow/deny/ask rules, modes, and how config interacts with authorization.
  </Card>
  <Card title="MCP servers" href="/mcp-servers">
    Register stdio and HTTP MCP servers in config.toml.
  </Card>
  <Card title="Custom models" href="/custom-models">
    -m, /model, BYOK, and OpenAI-compatible endpoints.
  </Card>
  <Card title="Authentication" href="/authentication">
    OAuth, device code, XAI_API_KEY, and credential storage.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    Terminal, color, auth recovery, and diagnostic probes.
  </Card>
</CardGroup>

## Next

<CardGroup cols={2}>
  <Card title="Configuration reference" href="/configuration-reference">
    Full key inventory after you know the load order.
  </Card>
  <Card title="Headless mode" href="/headless-mode">
    Non-interactive -p runs with env and tool allowlists for CI.
  </Card>
</CardGroup>