Config Switching
Keep several presets and switch the running visualizer between them.
kwybars switch-config lets you keep several presets and switch the running Kwybars between them without a restart. Kwybars watches one stable file, such as ~/.config/kwybars/current.toml, and switch-config changes which preset it points to.
Manual Workflow
Start Kwybars with the stable path:
kwybars --config ~/.config/kwybars/current.tomlThen switch presets:
kwybars switch-config --config ~/.config/kwybars/current.toml ~/.config/kwybars/custom/001_line_bottom.toml
kwybars switch-config --config ~/.config/kwybars/current.toml ~/.config/kwybars/custom/002_line_top.tomlcurrent.toml becomes a link to the preset you named. The preset files themselves are not changed.
This works only when the running Kwybars watches the same file you pass to switch-config. If Kwybars was started without --config, it watches the default path instead:
~/.config/kwybars/config.tomlIn that case leave --config out of the switch-config command too.
One Path for Everything
Set KWYBARS_CONFIG in your session environment and you never need --config:
export KWYBARS_CONFIG="$HOME/.config/kwybars/current.toml"kwybars
kwybars switch-config ~/.config/kwybars/custom/002_line_top.tomlIf the Active Path Is a Regular File
The first time you switch, the active path may still be an ordinary config file. Kwybars copies it to <name>.bak before replacing it with a link, so nothing is lost. If a different <name>.bak already exists, the command stops and asks you to move one of them away.
systemd --user
The packaged unit starts kwybars without --config, so it watches config.toml. To use the stable path, add an override:
systemctl --user edit kwybars.serviceUse:
[Service]
ExecStart=
ExecStart=/usr/bin/env kwybars --config %h/.config/kwybars/current.tomlUse %h for your home directory; ~ does not work in a unit file.
Then restart the service:
systemctl --user restart kwybars.serviceWallpaper Overlay Hooks
If you use a wallpaper tool that can run a hook after selecting a wallpaper, point it at kwybars image-overlay match:
kwybars image-overlay match --config ~/.config/kwybars/current.toml --overlay-dir ~/.config/kwybars/overlays "$wallpaper"For a wallpaper named forest.jpg, Kwybars looks for forest.png, forest.webp, forest.jpg, then forest.jpeg in the overlay directory. The command updates [image_overlay] in the active config, and the running visualizer reloads it.
Only the enabled and path lines of [image_overlay] change. Comments, spacing, and file permissions stay as they were.
If the active path is a link to a preset, the preset is edited and the link stays intact. If the link points outside its directory, the command stops and tells you which --config to use.
Example Hook Script
Create a small wrapper that changes the wallpaper first, then matches the overlay:
#!/usr/bin/env bash
set -euo pipefail
wallpaper="$1"
active_config="${KWYBARS_CONFIG:-$HOME/.config/kwybars/config.toml}"
overlay_dir="$HOME/.config/kwybars/overlays"
awww img "$wallpaper"
kwybars image-overlay match --config "$active_config" --overlay-dir "$overlay_dir" "$wallpaper"If you keep a stable preset link at ~/.config/kwybars/current.toml, set active_config to that path instead:
active_config="$HOME/.config/kwybars/current.toml"For hyprpaper, call Kwybars after hyprctl hyprpaper wallpaper:
monitor="DP-1"
wallpaper="$HOME/Pictures/wallpapers/forest.jpg"
hyprctl hyprpaper wallpaper "$monitor,$wallpaper"
kwybars image-overlay match --config ~/.config/kwybars/current.toml --overlay-dir ~/.config/kwybars/overlays "$wallpaper"