Configuration
The config file
Where riff's config.toml lives, how it is created and reloaded, and every section and key it reads.
Riff keeps its settings, tokens and keys in one TOML file. Most of it is
written for you by Settings and the setup guide. You only need to open it for
things Settings doesn’t cover. That includes [assist]: the app has no screen
for models or keys, so you set them here.
Location
Riff uses the first of these that applies:
| Order | Location |
|---|---|
| 1 | $RIFF_CONFIG, a full path to the file |
| 2 | $XDG_CONFIG_HOME/riff/config.toml |
| 3 | %APPDATA%\riff\config.toml on Windows |
| 4 | ~/.config/riff/config.toml |
export RIFF_CONFIG=/path/to/riff-config.tomlSettings → Storage shows the path in use and lets you copy it.
Creation
If the file doesn’t exist, riff creates it the first time it starts. The new file holds comments and examples only, so every feature stays at its default. Uncomment only what you want to change.
The file is written 0600 inside a 0700 folder, readable only by you. Riff
writes changes atomically and keeps the settings it doesn’t know about.
Reload
- Riff reads the file when it starts. After a hand edit, restart riff.
- Changes made in Settings or the setup guide (ignore patterns, Jira connections, GitHub token) take effect right away.
- A file that isn’t valid TOML is ignored: riff runs with defaults, assist
stays off, and it warns about it. A missing key never breaks the file. A
misspelled key inside
[assist.decision]does: riff reads the whole file as invalid. - There is no repository-local config.
Ignored legacy keys
These keys from the old terminal UI are still accepted and kept when riff
saves, but nothing reads them: whitespace, algorithm, context_lines,
theme, palette, scrolloff and editor. The app takes its display options
from Settings, and riff-diff from its command-line flags.
[assist]
Models, endpoints and limits for AI features. Off until model is set and a
key resolves. The full table is on Review assist.
| Key | Type | Default |
|---|---|---|
model, notes_model, chat_model, verify_model |
string | unset (notes_model and chat_model fall back to model) |
judgment_model |
string | jev-latest for jev, gpt-6-luna for builtin, none for bev |
judgment_engine |
jev, bev, builtin |
jev |
base_url, judgment_base_url |
string | provider default |
responses_api |
boolean | false |
api_key_env, judgment_api_key_env |
string | unset |
reasoning_effort, notes_reasoning_effort, chat_reasoning_effort |
string | see Review assist |
max_input_tokens_per_brief |
integer | unset |
digest_intent |
boolean | false |
judgment_repeat |
boolean | false |
review_engine |
scrutiny, pipeline |
scrutiny |
persona |
boolean | true |
deny_repos |
list of strings | [] |
prices."<model>" |
table: input, cached_input, output (USD per million tokens) |
riff’s list prices |
Subtables [assist.providers.*], [assist.profiles.*], [assist.tasks.*] and
[assist.decision] are for advanced routing and tuning.
[assist.decision]
Tuning for the built-in judgment engine. Leave it alone unless you know why.
| Key | Type | Default |
|---|---|---|
mode |
individual, batched |
individual |
prompt |
general, code |
general |
layout |
state_first, questions_first |
state_first (questions_first needs batched) |
responses_api |
boolean | false |
prefix_cache |
boolean | false (needs batched, questions_first, responses_api and judgment_repeat = false) |
reasoning_effort |
none, minimal, low, medium, high, xhigh, max, provider_default |
none |
max_output_tokens |
integer, above 0 | 256 |
temperature |
number, 0 to 2 | unset |
top_p |
number, above 0 up to 1 | unset |
prime |
boolean | true |
calibration |
three positive numbers | unset |
[ignore]
Paths riff never analyses. See Ignored files.
| Key | Type | Default |
|---|---|---|
defaults |
boolean | true |
patterns |
list of globs | [] |
[[ignore.repo]] repo, patterns |
string, list of globs | none |
[[jira]]
One entry per Jira Cloud connection. See Jira.
| Key | Type | Default |
|---|---|---|
id |
string | required |
base_url, email |
string | empty |
scope, projects, released_statuses |
list of strings | [] |
acceptance_field, testing_field, epic_link_field, team_field |
string | found by name |
[tokens]
Secrets, written by riff. Keep this table last.
| Key | Holds |
|---|---|
"<host>", such as "github.com" |
The GitHub token for that host. See GitHub |
"$default-host" |
The GitHub host you chose in Settings |
"$assist-key" |
The assist API key. Written by hand: no screen sets it |
"$judgment-key" |
The judgment API key (Jev only). Written by hand |
"$jira:<id>" |
The API token of the Jira connection <id> |
Example
[assist]model = "gpt-5.6-terra"judgment_model = "gpt-5.6-terra"api_key_env = "OPENAI_API_KEY"deny_repos = ["acme/secret"]
[ignore]patterns = ["**/*.snap"]
[[jira]]id = "work"base_url = "https://example.atlassian.net"email = "you@example.com"
[tokens]"github.com" = "ghp_…"Environment variables
| Variable | Effect |
|---|---|
RIFF_CONFIG |
Use this file instead of the default location |
XDG_CONFIG_HOME |
Base folder for the config file |
XDG_CACHE_HOME |
Base folder for the cache (~/.cache otherwise) |
RIFF_JIRA_TOKEN |
Jira API token for every connection, checked before [tokens] |
RIFF_LOG |
Log level, such as debug |
RIFF_ASSIST_TRACE |
A folder to write every Walkthrough article prompt and answer to |
OPENAI_API_KEY, TYPESAFE_API_KEY |
Assist and judgment keys, as described on Review assist |
GH_TOKEN and GITHUB_TOKEN are ignored on purpose.