KGL(1)

NAME
kgl - feed public-inbox messages into mail targets

SYNOPSIS
kgl [OPTIONS] COMMAND [ARGS]...

DESCRIPTION
kgl (korgalore) is a tool for feeding public-inbox git repositories and lei search results directly into mail targets such as Gmail, JMAP servers, IMAP servers, or local maildirs. It provides a workaround for Gmail's notorious hostility to high-volume technical mailing list traffic.

OPTIONS

--version
    Show the version and exit.

-v, --verbosity LVL
    Set logging verbosity. Valid levels: CRITICAL, ERROR, WARNING, INFO, DEBUG.

-c, --cfgfile PATH
    Path to configuration file. Default: ~/.config/korgalore/korgalore.toml

-l, --logfile PATH
    Path to log file for persistent logging.

--help
    Show help message and exit.

COMMANDS

  auth
Authenticate with configured targets.

kgl auth [TARGET]

If TARGET is specified, authenticate only that target. Otherwise, authenticate all targets requiring authentication. For Gmail targets, this opens a browser for OAuth authentication. For JMAP/IMAP targets, this verifies credentials are valid.

  bozofilter
Manage the bozofilter for blocking unwanted senders.

kgl bozofilter [OPTIONS]

-a, --add ADDRESS
    Add address(es) to the bozofilter (comma-separated).

-r, --reason TEXT
    Reason for adding (included as comment in the file).

-e, --edit
    Open the bozofilter file in $EDITOR.

-l, --list
    List all addresses in the bozofilter.

Messages from blocked addresses are silently skipped during delivery. The filter file is stored at ~/.config/korgalore/bozofilter.txt.

  edit-config
Open the configuration file in the default editor.

kgl edit-config

Opens the configuration file in $EDITOR or $VISUAL. If the file doesn't exist, creates it with example configuration. Validates TOML syntax after the editor closes.

  gui
Launch the GNOME taskbar application.

kgl gui

Starts a system tray indicator with automatic background syncing. Features include configurable sync intervals, Gmail re-authentication support, and menu options for manual sync, yanking messages, editing configuration, and managing the bozofilter.

  labels
List all available labels/folders for a target.

kgl labels [OPTIONS] TARGET

-i, --ids
    Include label/folder IDs in the output.

Useful for checking available labels before configuring deliveries.

  pull
Pull messages from configured lore and LEI deliveries.

kgl pull [OPTIONS] [DELIVERY_NAME]

-m, --max-mail NUM
    Maximum number of messages to pull (0 for all).

-n, --no-update
    Skip feed updates (useful with --force).

-f, --force
    Run deliveries even if no apparent updates.

If DELIVERY_NAME is specified, only process that delivery. Otherwise, process all configured deliveries including tracked threads.

  subscribe
Manage mailing list subscriptions.

kgl subscribe SUBCOMMAND [OPTIONS] [ARGS]

The add subcommand is the default and can be omitted: kgl subscribe URL is equivalent to kgl subscribe add URL.

Subcommands:

add URL
    Subscribe to a public-inbox feed or local lei search. Options: -t/--target, -l/--labels.

list
    List subscriptions. Use -p/--paused to show only paused subscriptions.

stop FEED_KEY
    Remove a subscription. Use --delete to also remove feed data.

pause FEED_KEY
    Temporarily pause a subscription.

resume FEED_KEY
    Resume a paused subscription. Use --skip to discard messages received while paused.

Subscriptions are stored as conf.d/sub-{feed_key}.toml files. Paused subscriptions are renamed to .toml.paused and excluded from configuration loading.

  track
Track email threads for updates via lei queries.

kgl track SUBCOMMAND [OPTIONS] [ARGS]

Subcommands:

add MSGID_OR_URL
    Start tracking a thread. Options: -t/--target, -l/--labels.

list
    List tracked threads. Use -i/--inactive to show only inactive threads.

stop TRACK_ID
    Stop tracking a thread. Use --delete to also remove lei search data.

pause TRACK_ID
    Temporarily pause tracking.

resume TRACK_ID
    Resume a paused or expired thread.

  track-subsystem
Track a kernel subsystem from MAINTAINERS file.

kgl track-subsystem [OPTIONS] [SUBSYSTEM_NAME]

-m, --maintainers PATH
    Path to MAINTAINERS file. If not specified, looks for ./MAINTAINERS in the current directory, then fetches from kernel.org (cached for 24 hours).

-t, --target NAME
    Target for deliveries. If not specified, the first configured target is used.

-l, --labels LABEL
    Labels to apply (repeatable).

--since   DATE
    Start date for query (default: 7.days.ago).

--threads
    Include entire threads when any message matches.

--forget
    Remove tracking for the subsystem.

-L, --list
    List all tracked subsystems. Shows the subsystem name, configuration file path, and delivery details (target and labels) for each tracked subsystem. When used, SUBSYSTEM_NAME is not required.

Creates lei queries for mailing list traffic and patches touching subsystem files. Configuration is stored in ~/.config/korgalore/conf.d/. Each generated configuration file includes a [subsystem] section with the human-readable subsystem name for identification.

  yank
Yank a single message or entire thread to a target.

kgl yank [OPTIONS] MSGID_OR_URL

-t, --target NAME
    Target to upload the message to. If not specified, the first configured target is used.

-l, --labels LABEL
    Labels to apply (repeatable or comma-separated).

-T, --thread
    Fetch and upload the entire thread.

Accepts either a message-id or a lore.kernel.org URL.

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.

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

ENVIRONMENT

EDITOR
    Editor used by edit-config and bozofilter --edit.

VISUAL
    Fallback editor if EDITOR is not set.

EXAMPLES
Initial setup:

    # Create and edit configuration
    kgl edit-config
    # Authenticate with Gmail
    kgl auth personal
    # Verify labels exist
    kgl labels personal
    # Test with verbose output
    kgl -v DEBUG pull

Regular use:

    # Pull all new messages
    kgl pull
    # Yank a specific message
    kgl yank '<msgid@example.com>'
    # Yank an entire thread
    kgl yank -T https://lore.kernel.org/lkml/msgid/
    # Track a thread for updates
    kgl track add '<msgid@example.com>'
    # Block a sender
    kgl bozofilter --add spammer@example.com

SEE ALSO
korgalore.toml(5), lei(1), git(1), notmuch(1)

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

BUGS
Report bugs by sending mail to tools@kernel.org

AUTHOR
Konstantin Ryabitsev <konstantin@linuxfoundation.org>