{{title}} — repartee
Author: outragedevs
Description: repartee — A modern terminal IRC client built with Ratatui, Tokio, and Rust. Scripting, theming, encrypted logging, and more.
Keywords: irc, terminal, tui, client, chat, repartee, ratatui, tokio, rust

# Configuration

## Config location

repartee stores its configuration in `~/.repartee/config.toml`. This file is created automatically on first run with sensible defaults.

The full directory layout:

    ~/.repartee/
      config.toml          # main configuration
      .env                 # credentials (passwords, SASL)
      themes/              # custom themes
      scripts/             # user scripts (Lua)
      logs/messages.db     # chat logs (SQLite)
      dicts/               # Hunspell dictionaries (.dic/.aff)
      sessions/            # Unix sockets for detached sessions
      certs/               # TLS certificates for web frontend

## Full annotated example

    [general]
    nick = "mynick"
    username = "mynick"
    realname = "repartee user"
    theme = "default"
    timestamp_format = "%H:%M:%S"
    flood_protection = true
    ctcp_version = "repartee"

    [display]
    nick_column_width = 8
    nick_max_length = 8
    nick_alignment = "right"       # "left", "right", or "center"
    nick_truncation = true
    nick_colors = true             # deterministic per-nick coloring (WeeChat-style)
    nick_colors_in_nicklist = true # also color nicks in the sidebar nick list
    nick_color_saturation = 0.65   # HSL saturation (0.0–1.0), truecolor only
    nick_color_lightness = 0.65    # HSL lightness (0.0–1.0), tune per theme
    show_timestamps = true
    scrollback_lines = 2000
    backlog_lines = 20             # history lines loaded when buffer opens (0 = off)
    mentions_buffer = true         # show Mentions buffer at top of sidebar

    [sidepanel.left]
    width = 20
    visible = true

    [sidepanel.right]
    width = 18
    visible = true

    [statusbar]
    items = ["active_windows", "nick_info", "channel_info", "lag", "time"]

    [servers.libera]
    label = "Libera"
    address = "irc.libera.chat"
    port = 6697
    tls = true
    tls_verify = true
    autoconnect = true
    channels = ["#repartee", "#secret mykey"]
    autosendcmd = "MSG NickServ identify pass; WAIT 2000; MODE $N +i"
    # nick = "othernick"           # per-server nick override
    # sasl_user = "mynick"
    # sasl_pass = "hunter2"
    # sasl_mechanism = "SCRAM-SHA-256"  # PLAIN (default), EXTERNAL, SCRAM-SHA-256
    # bind_ip = "192.168.1.100"   # bind to specific local IP (vhost)
    # auto_reconnect = true
    # reconnect_delay = 30
    # reconnect_max_retries = 10

    [image_preview]
    enabled = true
    protocol = "auto"              # "auto", "kitty", "iterm2", "sixel", "symbols"
    max_width = 0                  # 0 = auto
    max_height = 0                 # 0 = auto
    cache_max_mb = 100
    cache_max_days = 7
    fetch_timeout = 30             # seconds
    max_file_size = 10485760       # bytes (10 MB)
    kitty_format = "rgba"

    [logging]
    enabled = true
    encrypt = false
    retention_days = 0             # 0 = keep forever
    event_retention_hours = 72     # auto-prune join/part/quit/nick/kick/mode (0 = keep forever)
    exclude_types = []             # e.g. ["join", "part", "quit"]

    [aliases]
    ns = "/msg NickServ $*"
    cs = "/msg ChanServ $*"
    wc = "/close"
    j = "/join $0; /msg $0 hello everyone"

    [scripts]
    autoload = ["slap"]
    # debug = true

    [dcc]
    timeout = 300                  # seconds before pending requests expire
    own_ip = ""                    # override IP in DCC offers (empty = auto-detect)
    port_range = "0"               # "0" = OS-assigned, "1025 65535" = range
    autoaccept_lowports = false    # allow auto-accept from ports < 1024
    # autochat_masks = ["*!*@trusted.host"]  # hostmask patterns for auto-accept
    max_connections = 10

    [spellcheck]
    enabled = true
    languages = ["en_US"]              # Hunspell language codes
    dictionary_dir = ""                # default: ~/.repartee/dicts

    [web]
    enabled = false                    # enable embedded web frontend
    bind_address = "127.0.0.1"        # listen address (0.0.0.0 for LAN)
    port = 8443                        # HTTPS port
    tls_cert = ""                      # custom cert (empty = auto self-signed)
    tls_key = ""                       # custom key
    timestamp_format = "%H:%M"        # web UI timestamp format
    line_height = 1.35                 # CSS line-height for chat messages
    theme = "nightfall"                # web theme (nightfall, catppuccin-mocha, etc.)
    # cloudflare_tunnel_name = ""     # future: Cloudflare tunnel name

    [[ignores]]
    mask = "*!*@spammer.host"
    levels = ["ALL"]

## Sections explained

### `[general]`

Global identity and behavior. The `nick`, `username`, and `realname` are used as defaults for all servers unless overridden per-server. Set `theme` to the name of a theme file in `~/.repartee/themes/` (without the `.theme` extension).

### `[display]`

Controls how messages are rendered. `nick_column_width` sets the fixed-width column for nicks in chat view. `scrollback_lines` is the number of messages kept in memory per buffer. `backlog_lines` sets how many historical messages to load from the log database when a channel, query, or DCC buffer is first opened (0 to disable).

Mentions buffer: `mentions_buffer = true` (default) shows a persistent Mentions buffer pinned at the top of the sidebar. It aggregates all highlight mentions from all networks in a scrollable chat view. Scrollback is capped at 7 days or 1000 messages. Use `/clear` in the mentions buffer to wipe all stored mentions. Set to `false` to hide the buffer (mentions are still stored in the database and will reappear when re-enabled).

Nick coloring: `nick_colors = true` enables deterministic per-nick coloring (WeeChat-style). Each nick gets a consistent color based on a hash of its name. Truecolor terminals use an HSL hue wheel (~360 distinct colors); 256-color terminals fall back to a curated 68-color palette; 16-color terminals use 12 safe ANSI colors. Terminal capability is auto-detected (and re-detected on `repartee a` reattach). Set `nick_colors_in_nicklist = false` to keep the sidebar nick list using theme colors while chat messages stay colored. Tune `nick_color_saturation` and `nick_color_lightness` (0.0–1.0) per theme — dark themes work well with ~0.65, light themes around ~0.40.

### `[sidepanel]`

Left panel shows buffer list, right panel shows nick list. Set `visible = false` to hide a panel. Widths are in terminal columns.

### `[statusbar]`

Configure which items appear in the status line. Available items: `active_windows`, `nick_info`, `channel_info`, `lag`, `time`.

### `[servers.*]`

Each server gets a unique identifier (the key after `servers.`). The `channels` array lists channels to auto-join on connect. Channels with keys use the format `"#channel key"`.

Set `sasl_mechanism` to override automatic mechanism selection. Available: `PLAIN` (default), `EXTERNAL` (client TLS certificate), `SCRAM-SHA-256` (secure challenge-response).

Set `bind_ip` to bind to a specific local IP address when connecting. Useful for multi-IP hosts (vhosts/bouncers). Supports both IPv4 and IPv6 — DNS resolution automatically filters to match the address family. Can also be set per-connection with `/connect -bind=<ip>` or `/server add -bind=<ip>`.

### `[logging]`

Chat logging to SQLite. When `encrypt = true`, messages are encrypted with AES-256-GCM. `retention_days = 0` keeps logs forever. `event_retention_hours` controls how long event messages (join/part/quit/nick/kick/mode) are kept before automatic pruning — defaults to 72 hours. Set to `0` to keep event messages forever. Event pruning runs hourly in the background and is independent of `retention_days`.

### `[aliases]`

Custom command shortcuts. The key is the alias name, the value is the command template.

Templates support positional args (`$0`-`$9`), range args (`$1-`), all args (`$*`), context variables (`$C` channel, `$N` nick, `$S` server, `$T` buffer), and command chaining with `;`. If no `$` appears in the template, `$*` is appended automatically.

    [aliases]
    ns = "/msg NickServ $*"
    cs = "/msg ChanServ $*"
    wc = "/close"
    j = "/join $0; /msg $0 hello everyone"
    w = "/who $C"

Manage at runtime with `/alias` and `/unalias`.

### `[scripts]`

The `autoload` array lists script names to load on startup. Scripts live in `~/.repartee/scripts/` as `.lua` files.

### `[dcc]`

DCC (Direct Client-to-Client) chat settings. DCC CHAT establishes peer-to-peer TCP connections that bypass the IRC server.

`own_ip` overrides the IP address advertised in DCC offers. When empty, Repartee auto-detects from the IRC socket's local address (like irssi's `getsockname`). Set this to your public IP if behind NAT.

`port_range` controls the TCP port for DCC listeners. `"0"` lets the OS assign a free port. Use `"1025 65535"` or `"5000-5100"` to restrict to a range (useful for firewall rules).

`autochat_masks` is a list of `nick!ident@host` wildcard patterns. Incoming DCC CHAT offers matching any pattern are auto-accepted without prompting.

### `[spellcheck]`

Inline spell checking. When `enabled = true`, misspelled words are underlined in red while typing. Press Tab to cycle suggestions, Space to accept, Escape to revert. `languages` is a list of Hunspell language codes (e.g., `en_US`, `pl_PL`, `de_DE`) — a word is correct if any active dictionary accepts it. Place `.dic`/`.aff` files in `~/.repartee/dicts/` (or set `dictionary_dir` to a custom path).

### `[web]`

Embedded web frontend. When `enabled = true` and `WEB_PASSWORD` is set in `.env`, the app starts an HTTPS server alongside the terminal interface. Both share the same state — read a message on web, it's marked read on terminal, and vice versa.

Set `bind_address = "0.0.0.0"` to allow LAN access. TLS is always on — if no custom cert/key is provided, a self-signed certificate is auto-generated in `~/.repartee/certs/`.

The `theme` setting controls the web UI appearance. Available: `nightfall` (default dark), `catppuccin-mocha`, `tokyo-storm`, `gruvbox-light`, `catppuccin-latte`.

### `[[ignores]]`

Ignore patterns for filtering unwanted messages. Uses wildcard matching (`*!*@host`). Levels: `MSGS`, `PUBLIC`, `NOTICES`, `ACTIONS`, `JOINS`, `PARTS`, `QUITS`, `NICKS`, `KICKS`, `CTCPS`, `ALL`.

## Credentials

Passwords and SASL credentials should not go in `config.toml` — store them in `~/.repartee/.env` instead.

    # ~/.repartee/.env
    LIBERA_SASL_USER=mynick
    LIBERA_SASL_PASS=hunter2
    LIBERA_PASSWORD=serverpassword
    WEB_PASSWORD=mysecretpassword

Server credentials use the server identifier uppercased. `WEB_PASSWORD` is required for the web frontend — the server won't start without it.

## Runtime changes

- `/set section.field value` — change a config value at runtime. Changes are saved immediately.
- `/reload` — reload theme and config from disk.