# Configure Red

Canonical HTML: [Configure Red](https://getred.dev/docs/configuration). Website source: `b212874eefaf200143affa21c770fbb8855a4f5c`. Documented Red release: v0.9.1. Installer source: `b86a2ca4b92e9547d3b174910c82db8a259f5171`.

Keep the embedded defaults and add only the settings you want to change.

<a id="start-with-a-small-file"></a>

## Start with a small file

Red works without a configuration file. On macOS and Linux, create `~/.config/red/config.toml` when you want to override a default. The welcome screen can create a starter file without replacing existing settings.

```toml
theme = "red.json"
scrolloff = 8

[search]
ignorecase = true
smartcase = true

[keys.normal]
"Ctrl-s" = "Save"
```

Your file is layered over Red's embedded configuration, so it doesn't need to repeat unchanged settings.

<a id="check-a-change"></a>

## Check a change

```shell
red --check-config
red -c 'wrap = false' path/to/file
```

`--check-config` validates the effective user configuration and exits. The repeatable `-c` option applies a TOML override for one invocation.

<a id="common-sections"></a>

## Common sections

| Section              | Controls                                                                                        |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| Top level            | Theme, wrapping, scrolling, line numbers, release notes, diagnostics, and disabled plugins      |
| `[search]`           | Incremental search, highlighting, wrapping, and case behavior                                   |
| `[completion]`       | Automatic completion, buffer words, prefix length, and menu timing                              |
| `[agent]`            | Codex command, inline review behavior, followed tool calls, and explicitly enabled integrations |
| `[keys.MODE]`        | Mode-specific keybindings and chords                                                            |
| `[languages.ID]`     | Detection, comments, indentation, grammar, and language-server settings                         |
| `[plugin_config.ID]` | Settings owned by an enabled plugin                                                             |

[Open the commented default configuration](https://github.com/codersauce/red/blob/main/default_config.toml)