Media & UI

These commands control user-facing shell features that are not tied to one persistent surface.

Notifications

Action	Command	Description
Enable Do Not Disturb	`notification-dnd-set on`	Hide notification toasts. Notification history still fills.
Disable Do Not Disturb	`notification-dnd-set off`	Show notification toasts again.
Toggle Do Not Disturb	`notification-dnd-toggle`	Toggle notification toast visibility. Notification history still fills.
Show Do Not Disturb status	`notification-dnd-status`	Print the current Do Not Disturb state.
Send internal notification	`notification-show <summary>`	Create a Noctalia-origin notification with the provided summary text.
Invoke latest notification	`notification-invoke-latest`	Invoke the default action of the most recent active notification (raises/focuses the source app), mirroring a toast left-click.
Clear active notifications	`notification-clear-active`	Dismiss all currently visible active notifications.
Clear notification history	`notification-clear-history`	Remove all entries from notification history.

DND enable/disable IPC commands show a short OSD for the new state.

notification-show accepts a summary, and CLI usage can pass body as a second argument:

Terminal window

noctalia msg notification-show "Build finished"noctalia msg notification-show "Build finished" "All tests passed"

When a body argument is passed, the CLI forwards it as structured payload (summary + body) to the IPC handler.

For full control, pass a JSON payload object:

Terminal window

noctalia msg notification-show '{"app_name":"Noctalia","summary":"Build finished","body":"All tests passed","urgency":"low","timeout_ms":4000,"icon":"circle-check"}'

Supported JSON fields:

app_name (string): application label shown for the notification (default Noctalia)
summary (string, required for JSON mode): notification title text
body (string): body text
urgency (string): one of low, normal, critical
timeout_ms (integer): auto-dismiss timeout in milliseconds (0 keeps it persistent)
icon (string): icon hint. Plain names are treated as Noctalia glyphs (for example circle-check), while paths and URLs are treated as image icons.
category (string): freedesktop category
desktop_entry (string): desktop entry id

Clipboard

Section titled “Clipboard”

Action	Command	Description
Clear clipboard history	`clipboard-clear`	Clear clipboard history without opening the panel. Removes unpinned entries when any are pinned; otherwise clears everything. Does not ask for confirmation.

Media

Section titled “Media”

Action	Command	Description
Previous track	`media previous`	Ask the active MPRIS player to go to the previous item.
Next track	`media next`	Ask the active MPRIS player to go to the next item.
Play/pause toggle	`media toggle`	Toggle play/pause on the active MPRIS player.
Play	`media play`	Resume playback on the active MPRIS player.
Stop playback	`media stop`	Pause the active MPRIS player (falls back to the MPRIS `Stop` method for players that do not support pause). No-op when nothing is playing.
Previous player	`media previous-player`	Switch the active player to the previous available MPRIS player and pin it.
Next player	`media next-player`	Switch the active player to the next available MPRIS player and pin it.

Wallpaper

Section titled “Wallpaper”

Action	Command	Description
Random wallpaper now	`wallpaper-random`	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.
Next wallpaper	`wallpaper-next`	Advance to the next wallpaper in order immediately on all monitors.
Next wallpaper (one monitor)	`wallpaper-next <connector>`	Advance to the next wallpaper on the monitor named by connector (e.g. `DP-1`). Other monitors are unchanged. Respects per-monitor directory configuration and theme mode.
Previous wallpaper	`wallpaper-previous`	Go back to the previous wallpaper in order immediately on all monitors.
Previous wallpaper (one monitor)	`wallpaper-previous <connector>`	Go back to the previous 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`).
Set wallpaper (one monitor)	`wallpaper-set <connector> <path>`	Set only the monitor named by connector (e.g. `DP-1`). Remaining tokens are joined as the path. Other monitors are unchanged.

Wallpaper paths accept an image path (~ expanded) or color:#RRGGBB / color:#RRGGBBAA. Non-color paths must exist at call time.

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.

Theme

Section titled “Theme”

Action	Command	Description
Get theme mode	`theme-mode-get`	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`.
Set color scheme	`color-scheme-set builtin Noctalia`	Persist `[theme].source` and the palette for that source, then reload.
Apply templates	`templates-apply`	Rerender the enabled configured theme templates for the current palette without changing theme mode or firing shell palette hooks.

color-scheme-set accepts these source kinds:

builtin - built-in palette name, such as Noctalia
wallpaper - generator scheme, such as m3-tonal-spot, m3-content, m3-fruit-salad, m3-rainbow, m3-monochrome, vibrant, faithful, soft, dysfunctional, or muted
community - community palette id
custom - palette file name without .json under ~/.config/noctalia/palettes/

Screenshots

Section titled “Screenshots”

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`	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. 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.
Fullscreen (all monitors)	`screenshot-fullscreen all`	One combined desktop PNG spanning every monitor.

In picker mode, choose a connector from the top bar on any screen, or click the desktop to capture the monitor under the cursor. Errors list available connector names when the selector is unknown.