Config reference

Every config file lives at ~/.config/lys-shell/config.yaml. Each page below covers one section. Every field has a default; start with an empty file and add only what you want to change.

TIP

Editor intellisense via JSON Schema. Install the YAML extension for VSCode or yaml-language-server for Neovim, Helix, or Zed. The schema is written to ~/.config/lys-shell/schema.json on startup, and the config file lys-shell creates starts with the # yaml-language-server: $schema=./schema.json modeline that points the server at it.

Top-level sections

Section	What it controls
animations	Enter/exit and change animations for transient surfaces.
bar	Bar chrome: per-monitor layout, spacing, colors, and button styling.
clipboard	Clipboard history settings.
dropdowns	Per-dropdown foldout panel sizing.
general	Shell-wide settings that don't belong to any specific module.
launcher	Application launcher / dmenu (rofi replacement).
login	Login screen: the greeter and the lock screen, one screen in two modes.
mail-account	One mail account in the modules.mail per-account breakdown.
osd	On-screen display overlay for transient events like volume and brightness.
portal	Desktop-portal policy for sandboxed apps.
share-picker	Screen-share picker shown by xdg-desktop-portal when an app requests a
styling	Theme, palette, and rounding tokens applied shell-wide. Changes recompile the stylesheet.
toast-preset	A reusable toast preset, triggerable by id with lys-shell toast --preset <id>.
wallpaper	Wallpaper rendering, cycling, and per-monitor overrides.

Bar modules

Modules appear inside the bar.layout list. Each row links to the full reference.

Module	Purpose
battery	Battery level, charging state, and a dropdown with power-profile controls.
bitwarden	Bitwarden vault: the bar shows whether it is locked; the dropdown logs
bluetooth	Bluetooth connection status with a dropdown for pairing and managing devices.
brightness	Backlight control bar module.
cava	Audio frequency bars visualising the output stream.
clock	Clock module configuration.
cpu	CPU usage, frequency, and temperature.
custom	User-defined module that runs a shell command and renders the output in the bar.
dashboard	Quick-access button with a distro icon; opens the dashboard dropdown.
dropdown-dashboard-user-session	Settings for user session the in dashboard
hyprland-workspaces	Hyprland workspace indicators with click-to-switch.
idle-inhibit	Toggle that prevents screen dim, lock, and suspend while active.
keybind-mode	Current keybind-mode indicator for modal compositors.
keyboard-input	Active keyboard layout indicator.
lys-wm-workspaces	lys-wm workspace indicators with click-to-switch.
mail	Unread mail count, backed by a notmuch query.
mango-workspaces	MangoWM tag switcher module configuration.
media	Now-playing title and playback controls for the active MPRIS player.
microphone	Microphone input level and mute toggle.
netstat	Network traffic counters (up/down rates).
network	Network connection status with a dropdown for switching connections.
nightlight	Night light: warms the display colours, by hand or on a dawn/dusk schedule.
niri-workspaces	Niri workspace indicators with click-to-switch.
notifications	Notification center: icon in the bar, dropdown with history, DND toggle.
power	Shutdown, reboot, and logout menu.
power-profiles	Power profile indicator and switcher (power-profiles-daemon).
ram	Memory and swap usage.
recorder	Native screen recorder encoding on the GPU's video encoder.
screenshot	Screenshot capture button.
separator	A vertical rule between bar modules.
storage	Disk usage for a mount point.
sway-workspaces	sway workspace indicators with click-to-switch.
systray	System tray icons via the StatusNotifierItem protocol.
treeman	treeman worktree health across all registered repos, in a dropdown.
volume	Output volume control with a dropdown for device and app volumes.
weather	Current conditions with hourly and daily forecasts in a dropdown.
window-title	Active window title with optional app-icon prefix.
world-clock	Multiple timezones shown together in a dropdown.

Shared types

Every named type referenced across the config (Color, ClickAction, Size, and others) is documented on the types page.