Skip to Content
Kwybars
Usage

Command Line

Options of the kwybars command and its checking and config tools.

kwybars without a command runs the visualizer. The commands below check your setup or change config files, then exit.

kwybars [OPTIONS] [COMMAND]

Options

OptionDescription
-c, --config <PATH>Use the config at PATH instead of the default location
-h, --helpPrint help
-V, --versionPrint the version

--config works with every command, before or after it.

Checking Commands

CommandWhat it does
kwybars validate-configChecks the config, colors.toml, the theme, and the overlay image
kwybars doctorThe same check, plus the compositor, monitors, PipeWire, and the user service
kwybars list-themesLists the themes the config can name, and where each comes from

They print a report and exit with 0 when everything is fine and 1 when they found an error. Warnings, such as an unknown key, do not count as errors.

validate-config

kwybars validate-config --config ~/.config/kwybars/current.toml
config: /home/alice/.config/kwybars/current.toml (ok)
resolved config path: /home/alice/.config/kwybars/custom/line.toml
colors: /home/alice/.config/kwybars/colors.toml (ok)
theme: nord (built-in)
image overlay: disabled
config validation passed

A config with a mistake names the file, the line, and the key:

error: /home/alice/.config/kwybars/config.toml: TOML parse error at line 3, column 8
  |
3 | bars = "many"
  |        ^^^^^^
invalid type: string "many", expected usize

config validation failed: 1 error(s)

doctor

Run this first when the visualizer does not show up.

kwybars doctor
kwybars doctor (0.3.0)
config: /home/alice/.config/kwybars/config.toml (ok)
colors: /home/alice/.config/kwybars/colors.toml (not found)
theme: none
image overlay: disabled
overlay: position bottom, layer background
visualizer: layout line, 50 bars, 60 fps
session: wayland (WAYLAND_DISPLAY=wayland-1)
wayland: connected
layer shell: supported
fractional scale: supported
output DP-1: 3840x2160, scale 1.5, overlay
output DP-2: 2560x1440, scale 1, no overlay
pipewire: connected, capturing the default output (48000 Hz, 2 channels)
service: kwybars.service is installed, not enabled
log file: /home/alice/.local/state/kwybars/kwybars.log
summary: ok

What the lines mean when something is wrong:

LineMeaning
error: wayland: ...Kwybars is not running inside a Wayland session
error: layer shell: ...The compositor lacks the layer-shell protocol Kwybars needs, as GNOME does
output ...: no overlayThe config does not select that monitor. See choosing monitors
error: pipewire: ...PipeWire is not running or cannot be reached
service: ...Only information. Starting Kwybars from the compositor config is just as good

Config Commands

CommandWhat it does
kwybars switch-config <FILE>Makes the config path a link to FILE, so a running Kwybars switches to it
kwybars image-overlay match --overlay-dir <DIR> <WALLPAPER>Sets the image overlay to the image in DIR named like WALLPAPER

Both print what they did and exit with 0, or print the reason to stderr and exit with 1. They replace files in one step, so a running Kwybars never reads a half-written config. Config Switching shows how to use them.

switch-config also accepts -a, --active <PATH> as another spelling of --config.

Debug Commands

CommandWhat it does
kwybars debug audioShows a live level meter of the captured audio in the terminal
kwybars debug spectrumShows the analyzed bars in the terminal

They help to tell an audio problem from a display problem: if the meter moves but nothing appears on the desktop, the audio side works. Stop them with Ctrl-C.

Environment

VariableDescription
KWYBARS_CONFIGConfig path used when --config is not given
KWYBARS_THEMES_DIRExtra theme directories, separated by :
KWYBARS_LOGLog level, for example debug. Falls back to RUST_LOG
KWYBARS_LOG_FILELog file path

On this page