configuration

Configure slk to your taste.

slk reads a single TOML file at ~/.config/slk/config.toml. Every key is optional — sensible defaults cover everything. This page walks through each section in the order you'd typically reach for it.

The full example

Copy this into ~/.config/slk/config.toml as a starting point, then trim what you don't need.

[general]
default_workspace = "myteam"
use_slack_sections = true       # use real Slack sidebar sections (default).
                                # set false to use [sections.*] globs instead.

[appearance]
theme = "dracula"
timestamp_format = "3:04 PM"
image_protocol = "auto"   # auto | kitty | sixel | halfblock | off
max_image_rows = 20       # cap inline image height in terminal rows
max_image_cols = 60       # cap inline image width in terminal columns

[sidebar]
hide_inactive_after_days = 30   # auto-hide stale channels; 0 disables

[animations]
enabled = true
smooth_scrolling = true
typing_indicators = true

[notifications]
enabled = true
on_mention = true
on_dm = true
on_keyword = ["deploy", "incident"]
quiet_hours = "22:00-08:00"   # planned

[cache]
message_retention_days = 30
max_db_size_mb = 500
max_image_cache_mb = 200

[sections.Alerts]
channels = ["alerts", "ops", "*-alerts"]
order = 1

[sections.Engineering]
channels = ["eng-*", "deploys", "bugs"]
order = 2

# Per-workspace overrides — slug is whatever you chose at --add-workspace
# time; team_id ties it to the underlying Slack workspace.
[workspaces.work]
team_id = "T01ABCDEF"
order   = 1                     # rail position; 1-based, used by 1-9 keys
theme   = "dracula"
use_slack_sections = false      # this workspace uses [sections.*] globs;
                                # other workspaces still use Slack sections

[workspaces.work.sections.Engineering]
channels = ["eng-*", "deploys"]
order = 1

[theme]
primary    = "#4A9EFF"
accent     = "#50C878"
background = "#1A1A2E"
text       = "#E0E0E0"

[general]

Workspace-wide defaults.

[appearance]

How slk looks at the surface level.

[sidebar]

Keep the channel list focused on what you actually use.

[animations]

If your terminal is slow or you find motion distracting, set enabled = false and the others stop applying.

[notifications]

OS-level desktop notifications. Suppressed automatically when you're focused on the relevant channel.

[cache]

slk keeps a local SQLite cache of message history. These knobs control how aggressive it is.

Sidebar sections — Slack-native vs. globs

By default (use_slack_sections = true) slk reads your actual Slack sidebar sections — names, emoji, linked-list order, and channel/DM membership — and keeps them in sync over WebSocket. Reorder, rename, create, or delete sections in any other Slack client; slk catches up within a couple of seconds. Editing is read-only for v1: you do it in the official client, slk reflects the result.

Set use_slack_sections = false globally, or under a single [workspaces.<slug>], to opt that scope into the glob-based tables instead. Globs are also used as a fallback when Slack's section API is unreachable.

# Only consulted when use_slack_sections = false (globally or
# per-workspace), or when Slack's section API is unreachable.
[sections.Alerts]
channels = ["alerts", "ops", "*-alerts"]
order = 1

[sections.Engineering]
channels = ["eng-*", "deploys", "bugs"]
order = 2

[workspaces.<slug>] — per-workspace overrides

If you live in more than one Slack workspace, you can give each one its own rail position, theme, sidebar mode, and channel sections. The slug is whatever you typed at --add-workspace time; team_id ties it to the underlying Slack workspace.

[workspaces.work]
team_id = "T01ABCDEF"
order   = 1                     # rail position; 1-based, used by 1-9 keys
theme   = "dracula"             # overrides [appearance].theme
use_slack_sections = false      # this workspace uses [sections.*] globs;
                                # other workspaces still use Slack sections

[workspaces.work.sections.Alerts]
channels = ["alerts", "*-alerts"]
order = 1

[workspaces.work.sections.Engineering]
channels = ["eng-*", "deploys"]
order = 2

# A second workspace, ordered after the first, with no per-workspace
# sections — falls back to the global [sections.*] above.
[workspaces.side]
team_id = "T02XYZ"
order   = 2

[theme] — inline color overrides

If you like a built-in theme but want to nudge a few colors, set them under [theme]. They override the active theme's values, leaving everything else intact.

[theme]
primary    = "#4A9EFF"
accent     = "#50C878"
background = "#1A1A2E"
text       = "#E0E0E0"

For a full theme — every color, sidebar variants, etc. — write a custom theme file instead (next section).

Custom themes

Drop a .toml file into ~/.config/slk/themes/ to add a new theme. The filename (minus extension) is the theme's slug; set theme = "<slug>" under [appearance] to use it.

name = "My Theme"

[colors]
primary      = "#BD93F9"
accent       = "#50FA7B"
warning      = "#FFB86C"
error        = "#FF5555"
background   = "#282A36"
surface      = "#343746"
surface_dark = "#21222C"
text         = "#F8F8F2"
text_muted   = "#6272A4"
border       = "#44475A"

# Optional: separate sidebar/rail palette so the sidebar can be darker
# than the message pane (Slack's default look). Falls back to
# background/text/text_muted/surface_dark when omitted.
sidebar_background = "#19171D"
sidebar_text       = "#D1D2D3"
sidebar_text_muted = "#9A9B9E"
rail_background    = "#19171D"

Data paths

slk follows the XDG base directory spec.

PathContents
~/.config/slk/Configuration, custom themes
~/.local/share/slk/SQLite cache, tokens
~/.cache/slk/Avatars, image cache

Stuck or want a key documented that's not here? Open an issue.