KORGALORE.TOML(5)

NAME
korgalore.toml - configuration file for kgl (korgalore)

SYNOPSIS
~/.config/korgalore/korgalore.toml

DESCRIPTION
The korgalore.toml file configures korgalore (kgl), a tool for feeding public-inbox git repositories and lei search results into mail targets. The file uses TOML format and consists of several sections: targets, feeds, deliveries, gui, and main.

Additional configuration files can be placed in the ~/.config/korgalore/conf.d/ directory. Files matching *.toml are loaded in alphabetical order and merged with the main configuration.

SECTIONS

  [targets.<name>]
Targets define where messages will be delivered. Each target has a unique name and a type that determines which parameters are required.

Gmail Targets

    type
        Must be 'gmail'.

    credentials
        Path to the OAuth credentials JSON file from Google Cloud Console.

    token
        (Optional) Path to store the OAuth token. Defaults to ~/.config/korgalore/gmail-<name>-token.json.

Maildir Targets

    type
        Must be 'maildir'.

    path
        Path to the maildir directory. Created automatically if it doesn't exist. Tilde expansion is supported.

IMAP Targets

    type
        Must be 'imap'.

    server
        IMAP server hostname (e.g., 'imap.example.com').

    username
        Account username or email address.

    folder
        (Optional) Target folder for delivery. Default: 'INBOX'.

    auth_type
        (Optional) Authentication type: 'password' (default) or 'oauth2'.

    timeout
        (Optional) Connection timeout in seconds. Default: 60.

    For password authentication:

    password
        Password provided inline (less secure).

    password_file
        Path to file containing password (recommended). Either password or password_file must be provided.

    For OAuth2 authentication (Microsoft 365):

    client_id
        (Optional) Azure AD Application ID. Uses built-in default if not specified.

    tenant
        (Optional) Azure AD tenant ID. Default: 'common'.

    token
        (Optional) Path to OAuth2 token file.

JMAP Targets

    type
        Must be 'jmap'.

    server
        JMAP server URL (e.g., 'https://api.fastmail.com').

    username
        Account email address.

    token
        Bearer token provided inline (less secure).

    token_file
        Path to file containing bearer token. Either token or token_file must be provided.

    timeout
        (Optional) Request timeout in seconds. Default: 60.

Pipe Targets

    type
        Must be 'pipe'.

    command
        Command to pipe messages to. Labels are appended as arguments.

  [feeds.<name>]
Feeds define reusable feed URLs that can be referenced by multiple deliveries.

url The URL of the feed. Must start with https: for lore feeds or lei: for lei searches.

  [deliveries.<name>]
Deliveries define which feeds are delivered to which targets.

feed
    Name of a feed defined in the [feeds] section, or a direct URL (lore.kernel.org URL or lei:/path).

target
    Name of a target defined in the [targets] section.

labels
    (Optional) List of labels/folders to apply. Used by Gmail and JMAP targets. Ignored by Maildir and IMAP targets. For pipe targets, labels are appended as command-line arguments.

subfolder
    (Optional) Subfolder path for IMAP and Maildir targets.

    For IMAP: Combined with the target's base folder using / as separator (e.g., INBOX + Lists/LKML = INBOX/Lists/LKML).

    For Maildir: Creates a subdirectory under the target's base path.

    Maildir subfolders support strftime(3) format codes for date-based directories (e.g., %Y/%m becomes 2026/01). Templates are validated at startup and refreshed before each GUI sync.

    Ignored for Gmail, JMAP, and pipe targets.

  [subsystem]
Metadata section automatically generated by kgl track-subsystem in conf.d/ configuration files. This section is not used in the main configuration file.

name
    Human-readable name of the tracked subsystem (e.g., 'SELINUX SECURITY MODULE'). Used by kgl track-subsystem --list for display and by --forget for identification in log messages. Legacy configuration files without this section fall back to deriving the name from the filename.

  [gui]
Configuration for the GNOME taskbar application (kgl gui).

sync_interval
    Time in seconds between automatic syncs. Default: 300 (5 minutes).

  [main]
Global korgalore configuration.

user_agent_plus
    (Optional) String appended to the User-Agent header sent to remote servers. Helps server operators identify traffic from specific installations.

catchall_lists
    (Optional) List of mailing list addresses to exclude from track-subsystem queries. Default: ["linux-kernel@vger.kernel.org", "patches@lists.linux.dev"].

EXAMPLES
Minimal Gmail configuration:

    [targets.personal]
    type = 'gmail'
    credentials = '~/.config/korgalore/credentials.json'
    [deliveries.lkml]
    feed = 'https://lore.kernel.org/lkml'
    target = 'personal'
    labels = ['Lists/LKML']

Maildir with date-based archiving:

    [targets.archive]
    type = 'maildir'
    path = '~/Mail'
    [deliveries.lkml]
    feed = 'https://lore.kernel.org/lkml'
    target = 'archive'
    subfolder = 'Lists/LKML/%Y/%m'

IMAP with password authentication:

    [targets.myserver]
    type = 'imap'
    server = 'imap.example.com'
    username = 'user@example.com'
    folder = 'INBOX'
    password_file = '~/.config/korgalore/imap-password.txt'
    [deliveries.lkml]
    feed = 'https://lore.kernel.org/lkml'
    target = 'myserver'
    subfolder = 'Lists/LKML'

IMAP with OAuth2 (Microsoft 365):

    [targets.office365]
    type = 'imap'
    auth_type = 'oauth2'
    server = 'outlook.office365.com'
    username = 'user@company.com'
    [deliveries.lkml]
    feed = 'https://lore.kernel.org/lkml'
    target = 'office365'

JMAP (Fastmail):

    [targets.fastmail]
    type = 'jmap'
    server = 'https://api.fastmail.com'
    username = 'user@fastmail.com'
    token_file = '~/.config/korgalore/fastmail-token.txt'
    [deliveries.lkml]
    feed = 'https://lore.kernel.org/lkml'
    target = 'fastmail'
    labels = ['Lists/LKML']

Pipe target for custom processing:

    [targets.processor]
    type = 'pipe'
    command = '/usr/local/bin/process-mail.sh'
    [deliveries.lkml]
    feed = 'https://lore.kernel.org/lkml'
    target = 'processor'
    labels = ['--list=lkml']

Lei search delivery:

    [deliveries.mentions]
    feed = 'lei:/home/user/lei/mentions'
    target = 'personal'
    labels = ['INBOX', 'UNREAD']

Using named feeds for multiple deliveries:

    [feeds.lkml]
    url = 'https://lore.kernel.org/lkml'
    [deliveries.lkml-gmail]
    feed = 'lkml'
    target = 'personal'
    labels = ['Lists/LKML']
    [deliveries.lkml-archive]
    feed = 'lkml'
    target = 'archive'
    subfolder = 'Lists/LKML'

FILES

~/.config/korgalore/korgalore.toml
    Main configuration file.

~/.config/korgalore/conf.d/*.toml
    Additional configuration files, merged alphabetically.

~/.config/korgalore/bozofilter.txt
    Sender blocking filter (see kgl bozofilter).

~/.local/share/korgalore/
    Feed state and tracking data.

SEE ALSO
kgl(1), strftime(3), toml(5)

Full documentation: https://korgalore.docs.kernel.org/

AUTHOR
Konstantin Ryabitsev <konstantin@linuxfoundation.org>