KWYBARS(1)

📦 version 0.2.0, in nixpkgs unstable

💅 KWYBARS(1) — the user commands girlies ✨

okay so bestie, this is the kwybars family of commands: kwybars-daemon, kwybars-overlay, and kwybarsctl. it's a whole little squad, and i'm gonna introduce you to every single one 💖

🌸 NAME 🌸

kwybars — the GTK4 Wayland audio visualizer overlay, aka the prettiest thing on your desktop kwybars-daemon — the one that starts and supervises the Kwybars overlay (the mom friend) kwybars-overlay — the one that actually renders the visualizer overlay (the main character) kwybarsctl — the one that inspects and manages your Kwybars configuration (the nosy bestie who knows everything)

✨ SYNOPSIS ✨

kwybars-daemon [options]
kwybars-overlay [options]
kwybarsctl command [options]

🦋 DESCRIPTION 🦋

Kwybars is a Wayland-first desktop audio visualizer, and it ate. it renders GTK4 bars as a transparent layer-shell overlay, usually anchored to a desktop edge. like, your music is playing and your screen is just vibing along. iconic behavior.

the recommended runtime entrypoint is kwybars-daemon. the daemon watches audio activity, starts kwybars-overlay when audio becomes active, stops it after silence when configured to do so, and shares one audio frame stream with the overlay process. she's the group-chat admin of this whole operation fr fr 🫶

the kwybars-overlay binary owns the GTK/layer-shell window and the rendering loop. it can be launched directly for development or troubleshooting, but daemon launch is preferred for normal desktop use. so like, yes you can text the main character directly, but the group chat works better 😭

the kwybarsctl binary provides read-only diagnostics plus safe config and image-overlay helpers. lowkey the most useful one for when something's acting up.

🎀 DAEMON OPTIONS 🎀

  • -h, --help — shows daemon help. the "who am i" button 🫶
  • -c, --config PATH — loads a specific configuration file
  • --config=PATH — loads a specific configuration file (same thing, equals-sign flavor ✨)

💜 OVERLAY OPTIONS 💜

  • -h, --help — shows overlay help
  • -c, --config PATH — loads a specific configuration file
  • --config=PATH — loads a specific configuration file (identical twin, we stan consistency)

👑 CONTROL COMMANDS 👑

  • switch-config [--active PATH] TARGET — atomically replaces the active config path with a symlink pointing at TARGET. by default, the active path is the normal Kwybars config path. it's a glow-up for your symlink, no cap 💅
  • image-overlay match --overlay-dir DIR [--config PATH] WALLPAPER — matches WALLPAPER by filename stem against images in DIR, then sets [image_overlay].enabled and [image_overlay].path in the selected config. the lookup order is png, webp, jpg, then jpeg — she checks in that exact order, don't @ her 🍓
  • validate-config [--config PATH] — validates the selected config file, the adjacent colors.toml, and the configured theme. a positional config path may be used instead of --config. self-care for your dotfiles ✨
  • doctor [--config PATH] — prints local runtime diagnostics, including Wayland session detection, Cava availability, config parse status, theme status, selected overlay values, and overlay frame-source state. literally the "what's wrong with me" quiz but for your setup 🩺
  • list-themes [--config PATH] — lists available user, packaged, and source-checkout themes using the same precedence as the runtime. window shopping for aesthetics 🛍️
  • -h, --help — shows control command help

🌈 CONTROL OPTIONS 🌈

  • -a, --active PATH — the active config path to update for switch-config
  • -c, --config PATH — the config path to update, validate, inspect, or use for theme lookup. she does it all 💅
  • --overlay-dir DIR — directory containing images for image-overlay match lookups

🧚 CONFIGURATION 🧚

the default config path is resolved in this order, first one wins bestie:

  1. KWYBARS_CONFIG
  2. $XDG_CONFIG_HOME/kwybars/config.toml
  3. $HOME/.config/kwybars/config.toml
  4. ./kwybars.toml

if no config exists, Kwybars uses built-in defaults. no config, no problem, she's got you 🫶

packaged examples are installed under /usr/share/doc/kwybars/examples/, and source checkouts include examples under assets/examples/.

adjacent colors.toml files can override visualizer colors for the active config. cute little palette swap, we love to see it 🎨

🦄 FILES 🦄

  • ~/.config/kwybars/config.toml — the default user configuration file
  • ~/.config/kwybars/colors.toml — optional adjacent color override file
  • ~/.config/kwybars/themes/ — user theme directory
  • /usr/share/kwybars/themes/ — packaged built-in themes
  • /usr/share/doc/kwybars/examples/ — packaged example configurations
  • /usr/lib/systemd/user/kwybars-daemon.service — the packaged user service
  • ~/.local/state/kwybars/daemon.log — default daemon log file when XDG_STATE_HOME is unset
  • ~/.local/state/kwybars/overlay.log — default overlay log file when XDG_STATE_HOME is unset

⭐ ENVIRONMENT ⭐

  • KWYBARS_CONFIG — overrides the default config path
  • KWYBARS_THEMES_DIR — overrides the packaged built-in theme directory
  • KWYBARS_LOG — controls tracing verbosity. falls back to RUST_LOG when unset
  • KWYBARS_LOG_FILE — overrides the log file target for the current process
  • KWYBARS_FRAME_SOCKET — internal daemon-to-overlay frame stream socket. normally set by kwybars-daemon (so like, hands off unless you know what you're doing 🙈)
  • KWYBARS_DISABLE_NOTIFICATIONS — internal flag used to suppress duplicate overlay notifications when launched by the daemon
  • GSK_RENDERER — GTK renderer override. the overlay defaults this to cairo when unset
  • WAYLAND_DISPLAY — Wayland display socket name. required for overlay display, though the daemon can recover from some missing environment cases by inspecting XDG_RUNTIME_DIR. she's resilient like that 💪

🔥 EXAMPLES 🔥

start the daemon manually:

kwybars-daemon

start with an explicit config:

kwybars-daemon --config ~/.config/kwybars/config.toml

run the overlay directly:

kwybars-overlay --config ./assets/examples/wave.toml

validate config:

kwybarsctl validate-config

run diagnostics:

kwybarsctl doctor

list themes:

kwybarsctl list-themes

switch the active config symlink:

kwybarsctl switch-config ~/.config/kwybars/presets/wave.toml

match a wallpaper to an image overlay:

kwybarsctl image-overlay match --overlay-dir
~/.config/kwybars/wallpaper-overlays
~/Pictures/wallpapers/forest.jpg

enable the packaged user service:

systemctl --user enable --now kwybars-daemon.service

💀 SEE ALSO 💀

cava(1), systemctl(1), journalctl(1) — go read those too, iykyk 📚

anyway that's the whole page, bestie 💜 this was Kwybars 0.1.9, dated May 2026 — drink some water, systemctl --user enable --now your dreams, and go make your desktop gorgeous ✨🎀🦋

📦 where this page comes from