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
| Option | Description |
|---|---|
-c, --config <PATH> | Use the config at PATH instead of the default location |
-h, --help | Print help |
-V, --version | Print the version |
--config works with every command, before or after it.
Checking Commands
| Command | What it does |
|---|---|
kwybars validate-config | Checks the config, colors.toml, the theme, and the overlay image |
kwybars doctor | The same check, plus the compositor, monitors, PipeWire, and the user service |
kwybars list-themes | Lists 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.tomlconfig: /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 passedA 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 doctorkwybars 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: okWhat the lines mean when something is wrong:
| Line | Meaning |
|---|---|
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 overlay | The 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
| Command | What 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
| Command | What it does |
|---|---|
kwybars debug audio | Shows a live level meter of the captured audio in the terminal |
kwybars debug spectrum | Shows 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
| Variable | Description |
|---|---|
KWYBARS_CONFIG | Config path used when --config is not given |
KWYBARS_THEMES_DIR | Extra theme directories, separated by : |
KWYBARS_LOG | Log level, for example debug. Falls back to RUST_LOG |
KWYBARS_LOG_FILE | Log file path |