riff

    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
    Terminal window
    export RIFF_CONFIG=/path/to/riff-config.toml

    Settings → 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.