# Configuration

This page lists every config file key CRIEW currently accepts,
how defaults and fallbacks are resolved,
and which minimal settings fit the common lore,
IMAP,
reply,
and code-browser workflows.

## Default paths

- Preferred config file:
  `~/.criew/criew-config.toml`
- On first run,
  CRIEW writes a minimal file there if neither
  `~/.criew/criew-config.toml`
  nor the older
  `~/.criew/config.toml`
  exists.
- Normal runtime root:
  `~/.criew/`
- Relative paths in the config file resolve from the config file directory,
  not from the shell's current working directory.
- CRIEW creates missing runtime directories on startup.

## Start with one of these

### Lore only

Use this when you only sync lore mailboxes:

```toml
[source]
mailbox = "io-uring"
```

Run:

```bash
criew sync
criew tui
```

### IMAP plus reply plus code browser

Use this when you want `My Inbox`,
reply sending,
and a local kernel tree:

```toml
[source]
mailbox = "io-uring"

[imap]
email = "you@example.com"
user = "you@example.com"
pass = "app-password"
server = "imap.example.com"
serverport = 993
encryption = "ssl"

[kernel]
tree = "/path/to/linux"
```

Run:

```bash
criew doctor
criew sync --mailbox INBOX
criew tui
```

## Resolution rules

- Omitted storage paths are derived from `storage.data_dir`.
- `b4.path` wins over every fallback.
  If it is unset,
  CRIEW tries `CRIEW_B4_PATH`,
  `./vendor/b4/b4.sh`,
  the embedded runtime copy under `<data_dir>/vendor/b4/b4.sh`,
  and then `b4` in `PATH`.
- `imap.user` falls back to `imap.email`.
- `imap.proxy` falls back to
  `CRIEW_IMAP_PROXY`,
  `ALL_PROXY`,
  `all_proxy`,
  `HTTPS_PROXY`,
  `https_proxy`,
  `HTTP_PROXY`,
  and `http_proxy`,
  in that order.
- `imap.mailbox` is still accepted as a historical alias for `source.mailbox`,
  but new config should use `source.mailbox`.
- When IMAP config is complete,
  CRIEW can use `INBOX` as the default active mailbox.
  Without complete IMAP config,
  CRIEW falls back to `source.mailbox`.
- `ui.keymap = "custom"` currently changes only the displayed scheme label.
  Navigation still follows the default layout.
- `kernel.tree` is loaded first.
  Entries from `kernel.trees` are appended after it,
  and duplicate resolved paths are removed.

## Full config reference

### `[storage]`

- `storage.data_dir`:
  Optional path.
  Default is `~/.criew/`.
  This is the runtime root used by the derived defaults for the database,
  raw mail cache,
  patch output,
  logs,
  and embedded vendor assets.
- `storage.database`:
  Optional path.
  Default is `<data_dir>/db/criew.db`.
  This SQLite database stores synced mail,
  threads,
  patch metadata,
  and reply send state.
- `storage.raw_mail_dir`:
  Optional path.
  Default is `<data_dir>/mail/raw`.
  CRIEW stores raw `.eml` files here for preview rendering,
  reply draft seeding,
  and fallback recovery when parsed state is incomplete.
- `storage.patch_dir`:
  Optional path.
  Default is `<data_dir>/patches`.
  `b4` downloads and patch workflow output are written here.

### `[logging]`

- `logging.dir`:
  Optional path.
  Default is `<data_dir>/logs`.
  CRIEW writes `criew.log` and `error.log` here.
- `logging.filter`:
  Optional string.
  Default is `info`.
  CRIEW passes this to tracing's filter parser.
  Simple values such as `trace`,
  `debug`,
  `info`,
  `warn`,
  and `error` are the safest choices.

### `[b4]`

- `b4.path`:
  Optional path.
  Use this when you want CRIEW to call one specific `b4` binary or wrapper
  instead of the normal fallback chain.

### `[source]`

- `source.mailbox`:
  Optional string.
  Default is `linux-kernel`.
  This is the lore mailbox used by `criew sync` when you do not pass
  `--mailbox`.
  It is also the fallback active mailbox when IMAP is not fully configured.
- `source.lore_base_url`:
  Optional string.
  Default is `https://lore.kernel.org`.
  Use this only when you need a different lore base URL.

### `[imap]`

This section is optional unless you want real IMAP `INBOX` sync.
CRIEW treats the IMAP config as complete only when the login identity,
password,
server,
port,
and encryption mode are all present.

- `imap.mailbox`:
  Historical compatibility alias for `source.mailbox`.
  Supported for reading and `config get/set`,
  but not recommended for new files.
- `imap.email`:
  Optional string.
  CRIEW uses this as your self address for mail matching.
  It also becomes the login identity when `imap.user` is omitted.
  `criew doctor` uses it before `git config user.email` when resolving the
  self address,
  and reply composition keeps it as an additional self address for recipient
  filtering.
- `imap.user`:
  Optional string.
  Alias:
  `imapuser`.
  This is the IMAP login account.
  Gmail usually expects the full email address here.
  If omitted,
  CRIEW falls back to `imap.email`.
- `imap.pass`:
  Optional string.
  Alias:
  `imappass`.
  This is the IMAP password or app password.
- `imap.server`:
  Optional string.
  Alias:
  `imapserver`.
  This is the IMAP server host name.
- `imap.serverport`:
  Optional integer.
  Alias:
  `imapserverport`.
  Required for real IMAP sync.
  Valid values are `1` through `65535`.
  `0` is rejected.
- `imap.encryption`:
  Optional string.
  Alias:
  `imapencryption`.
  Accepted values are `tls`,
  `ssl`,
  `starttls`,
  and `none`.
  `ssl` is accepted as the same runtime mode as `tls`.
- `imap.proxy`:
  Optional string.
  Supported schemes are `http://`,
  `socks5://`,
  and `socks5h://`.
  When omitted,
  CRIEW falls back to the proxy environment variables listed above.

### `[ui]`

- `ui.startup_sync`:
  Optional boolean.
  Default is `true`.
  When enabled,
  CRIEW auto-syncs enabled subscriptions after the TUI starts.
- `ui.keymap`:
  Optional string.
  Default is `default`.
  Supported values are `default`,
  `vim`,
  and `custom`.
  `default` uses `j/l` for focus and `i/k` for movement.
  `vim` uses `h/l` for focus and `j/k` for movement,
  plus `gg`,
  `G`,
  and `qq`.
  `custom` currently keeps the default navigation behavior.
- `ui.inbox_auto_sync_interval_secs`:
  Optional integer.
  Default is `30`.
  This controls the delay between `My Inbox` background sync runs while the
  TUI stays open.
  The value must be greater than `0`.

### `[kernel]`

- `kernel.tree`:
  Optional path.
  One kernel tree root shown in the code browser pane.
- `kernel.trees`:
  Optional TOML array of paths.
  Additional kernel tree roots shown as top-level entries in the code browser.
  Use this when you want to switch between multiple working trees.

## Edit config from the TUI

Open the command palette with `:`,
then use one of these commands:

- `config show`
  opens the visual config editor.
- `config show <key>`
  shows the current file value,
  or the effective runtime fallback when the key is unset.
- `config get <key>`
  is the same read-only lookup form.
- `config edit [key]`
  opens the visual editor,
  optionally focused on one supported field.
- `config set <key> <value>`
  writes a TOML literal back to the config file and reloads runtime config.

Examples:

```text
config get source.mailbox
config set ui.keymap vim
config set kernel.trees ["/path/to/linux", "/path/to/linux-next"]
```

`config.path` is a runtime-only value exposed by `config get`.
It reports the active config file path,
but it is not a file key you set in TOML.

## Constraints

- `v0.0.1` and later support only the CRIEW naming set:
  `criew`,
  `~/.criew/`,
  `criew-config.toml`,
  `criew.db`,
  `CRIEW_B4_PATH`,
  and `CRIEW_IMAP_PROXY`.
- Courier-era names such as `~/.courier`,
  `courier-config.toml`,
  `courier.db`,
  `COURIER_B4_PATH`,
  and `COURIER_IMAP_PROXY`
  are intentionally unsupported.
- `git send-email` is required only for reply sending.
- The kernel tree is optional,
  but code browsing and patch context are much more useful when it is set.

## See also

- [Install and Setup](Install-and-Setup.md)
- [Sync and TUI](Sync-and-TUI.md)
- [Patch and Reply](Patch-and-Reply.md)
- [Keybindings](Keybindings.md)