# 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"` uses `ui.keymap_base`
plus any overrides from `[ui.custom_keymap]`.
The `:keymap` editor writes these values back to the config file.
- `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` uses `ui.keymap_base`
plus any overrides from `[ui.custom_keymap]`.
- `ui.keymap_base`:
Optional string.
Supported values are `default` and `vim`.
This selects the preset that seeds `ui.keymap = "custom"`.
When omitted,
CRIEW infers the base from `ui.keymap`:
`vim` implies `vim`,
and every other scheme implies `default`.
- `ui.custom_keymap`:
Optional TOML table.
This overrides the main-page navigation actions used by
`ui.keymap = "custom"`.
Supported fields are:
`focus_prev`,
`focus_next`,
`move_up`,
`move_down`,
`jump_top`,
`jump_bottom`,
and `quick_quit`.
Each field is a TOML array of 1-2 printable keys,
for example `["g", "g"]` or `["z"]`.
- `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.
- `keymap`
opens the visual keymap editor for main-page navigation.
- `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
keymap
config get source.mailbox
config set ui.keymap vim
config set ui.keymap_base default
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)