Reveal matching bar instance(s). Omit both arguments to show every bar on every output.
Hide bar
bar-hide [bar-name] [monitor-selector]
Hide matching bar instance(s) and block edge/pointer reveal until the next show/toggle. Omit both arguments to hide every bar.
Toggle bar
bar-toggle [bar-name] [monitor-selector]
Toggle visibility for matching bar instance(s). Omit both arguments to toggle every bar. Does not block edge reveal on hide (use bar-hide to stay hidden until bar-show ).
Temporarily move matching bar instance(s) to the top or overlay layer-shell layer. overlay shows the bar above fullscreen apps; attached panels follow the bar’s layer. Omit bar-name to update every bar.
Dispatch an event to a plugin entry’s onIpc. Target can be focused, all, a monitor selector such as DP-1, or a bar-qualified target such as focused:default.
Manage plugins
plugins <subcommand> ...
List, enable, disable, or update plugins and manage sources (list, enable, disable, update, source). See Plugins.
Switch to a random wallpaper immediately on all monitors.
Random wallpaper (one monitor)
wallpaper-random <connector>
Switch to a random wallpaper on the monitor named by connector (e.g. DP-1). Other monitors are unchanged. Respects per-monitor directory configuration and theme mode.
Get wallpaper
wallpaper-get
Print the default wallpaper path persisted in settings.toml.
Get wallpaper (one monitor)
wallpaper-get <connector>
Print the effective wallpaper path for the monitor named by connector (e.g. DP-1).
Set wallpaper (all monitors)
wallpaper-set <path>
Set every connected monitor and the default wallpaper, persisted to settings.toml (per-monitor entries plus wallpaper.default.path). Same behavior as choosing All monitors in the wallpaper panel. Use an image path (~ expanded) or color:#RRGGBB / color:#RRGGBBAA; non-color paths must exist at call time.
Set wallpaper (one monitor)
wallpaper-set <connector> <path>
Set only the monitor named by connector (e.g. DP-1 - same value as per-monitor keys in config and the wallpaper panel). Remaining tokens are joined as the path. Other monitors are unchanged. Same path and color rules as the all-monitor form.
The CLI forwards everything after the command as one string (noctalia msg wallpaper-set …), so noctalia msg wallpaper-set DP-1 /home/you/My Pictures/wall.jpg still yields a correct path when the shell passes separate arguments after the command (they are rejoined with spaces for parsing).
Start moving, resizing, rotating, and removing desktop widgets.
Exit edit mode
desktop-widgets-exit
Leave desktop widget edit mode.
Toggle edit mode
desktop-widgets-toggle-edit
Switch edit mode on or off.
Show widgets
desktop-widgets-show
Reveal desktop widgets now, even when the saved setting is disabled. Runtime only — does not change the saved setting, and resets on restart.
Hide widgets
desktop-widgets-hide
Hide desktop widgets now, tearing down their instances so rendering and compute stop. Runtime only — does not change the saved setting, and resets on restart.
Toggle widgets
desktop-widgets-toggle
Flip current visibility; prints shown or hidden. Runtime only — does not change the saved setting. Changing the saved Desktop > Widgets toggle cancels the override.
Clear clipboard history without opening the panel. Removes unpinned entries when any are pinned; otherwise clears everything. Does not ask for confirmation.
Ask the active MPRIS player to go to the previous item.
Play/pause toggle
media toggle
Toggle play/pause on the active MPRIS player.
Stop playback
media stop
Stop the active MPRIS player and clear it from Noctalia’s active-player selection (so bar media widgets can hide when configured to hide without an active player).
Next track
media next
Ask the active MPRIS player to go to the next item.
Print the current resolved theme mode: dark or light (from [theme].mode or from the [location] schedule when mode is auto).
Toggle theme mode
theme-mode-toggle
Switch between dark and light theme mode (same as the bar control when [theme].mode is not auto).
Set theme mode
theme-mode-set dark
Persist [theme].mode in settings.toml and reload. Pass dark, light, or auto (example shows dark).
Get color scheme
color-scheme-get
Print the active palette selection as two tokens: builtin Noctalia, wallpaper m3-content, community Oxocarbon, or custom MyScheme (matches [theme].source and the corresponding palette field).
Set color scheme
color-scheme-set builtin Noctalia
Persist [theme].source and the palette for that source, then reload. builtin - built-in palette name (e.g. Noctalia). wallpaper - generator scheme (m3-tonal-spot, m3-content, m3-fruit-salad, m3-rainbow, m3-monochrome, vibrant, faithful, soft, dysfunctional, muted). community - community palette id. custom - palette file name without .json under ~/.config/noctalia/palettes/.
Apply templates
templates-apply
Rerender the enabled configured theme templates for the current palette without changing theme mode or firing shell palette hooks.
Alt+Tab-style overlay: a dimmed fullscreen layer with a centered grid of open windows (application icon, title, optional app name). There is no [shell.window_switcher] configuration block yet - wire your compositor shortcut to the IPC commands below (for example Hyprland bind = ALT, Tab, exec, noctalia msg window-switcher).
Action
Command
Description
Open
window-switcher
Show the switcher on the preferred monitor (pointer, keyboard focus, or first output).
Close
window-switcher close
Hide the overlay without changing focus. hide is an alias.
While the overlay is open it takes exclusive keyboard focus on its layer surface:
Tab / Shift+Tab - cycle selection
Arrow keys - move within the grid (up to five columns)
Enter - focus the selected window and close
Escape - close without switching
Pointer - click a tile to switch; click the close control on a tile to close that window
The window list refreshes while the overlay stays open (new windows, closed windows, and title changes such as Discord channel switches). Selection stays on the same window when its title updates.
Requires compositor support for wlr-screencopy-unstable-v1. Uses the global [shell.screenshot] output policy (directory, filename pattern, freeze, save to file, clipboard, pipe command). See Shell settings.
Action
Command
Description
Region screenshot
screenshot-region [widget-name]
Start interactive region capture (drag to select; press [keybinds].cancel to dismiss).
Fullscreen screenshot
screenshot-fullscreen
Capture the focused monitor (compositor-selected output, active toplevel, keyboard focus, or recent pointer).
Fullscreen (pick monitor)
screenshot-fullscreen pick
Open the display picker on multi-monitor setups (same UI as the bar fullscreen action). Choose a connector from the top bar on any screen, or click the desktop to capture the monitor under the cursor. On a single monitor, captures immediately.
Fullscreen (specific output)
screenshot-fullscreen DP-2
Capture one output without the picker. Pass the Wayland connector name (e.g. DP-1, HDMI-A-1) or a word-boundary match in the output description. Errors list available connector names when the selector is unknown.
