command-center/omp-docs/tools/noctalia-shell.md

type, title, description, resource, tags, timestamp, verified

type	title	description	resource	tags	timestamp	verified
reference	Noctalia Shell	Native desktop environment for Niri — launcher, control center, settings, lock screen, session menu, hotkey overlay, media controls, and system management.	https://github.com/Noctalia/noctalia	noctalia niri wayland desktop-environment launcher control-center session-management	2026-10-09	2026-10-09

Noctalia Shell

Noctalia is a native, minimal desktop environment for the Niri compositor. It provides an application launcher, control center, settings GUI, lock screen, session menu, hotkey overlay, media controls, brightness/volume controls, wallpaper management, and system-level utilities.

Version: 5.2.1-1.1 Binary: /usr/bin/noctalia (native Qt application, no Quickshell dependency) Config: ~/.config/noctalia/

---

Architecture

Noctalia is a native Qt binary that communicates with Niri and system services via direct IPC (noctalia msg) and shell scripts (spawn-sh). It does not depend on Quickshell.

IPC Interface

All primary functionality is exposed via the noctalia msg command:

noctalia msg <command>

See noctalia msg --help for the complete command list.

Historical Note: v4.x used Quickshell IPC (qs -c noctalia-shell ipc call ...), but v5+ is a native binary with its own IPC interface.

---

Command Reference

Commands are grouped by functional area.

Shells / Surfaces

Command	Description
bar-show [bar-name]	Show a named bar or all bars
bar-hide [bar-name]	Hide a named bar or all bars
bar-layer-set <layer>	Set bar layer (e.g., top, bottom)
bar-reserve-toggle [bar-name]	Temporarily toggle reserve space
bar-toggle [bar-name]	Toggle visibility for a named bar or all bars
dock-hide	Hide the dock (persists override)
dock-reload	Reload dock configuration
dock-show	Show the dock (persists override)
dock-toggle	Toggle dock visibility (persists override)
panel-close [id]	Close the active or named panel
panel-open <id> [context]	Open a panel by id, optionally with context (e.g., launcher /emo, control-center audio)
panel-toggle <id> [context]	Toggle a panel by id, optionally with context
settings-close	Close the settings window
settings-open [context]	Open the settings window, optionally at a specific section
settings-open-plugin <plugin-id>	Open settings at a plugin's settings (e.g., noctalia/notes)
settings-open-widget [bar-name] [widget-name]	Open settings at a bar widget
settings-toggle [context]	Toggle the settings window, optionally at a specific section
window-switcher [action]	Open or close the window switcher overlay

Lockscreen / Session

Command	Description
session lock	Lock the screen
session lock-and-suspend	Lock and suspend the system
lockscreen-widgets-edit	Open the lockscreen widgets editor
lockscreen-widgets-exit	Close the lockscreen widgets editor
lockscreen-widgets-toggle-edit	Toggle lockscreen widgets edit mode

Desktop Widgets

Command	Description
desktop-widgets-edit	Open the desktop widgets editor
desktop-widgets-exit	Close the desktop widgets editor
desktop-widgets-hide	Hide desktop widgets (runtime only)
desktop-widgets-show	Show desktop widgets (runtime only)
desktop-widgets-toggle	Toggle desktop widgets visibility (runtime only)
desktop-widgets-toggle-edit	Toggle desktop widgets edit mode

Greeter

Command	Description
greeter-sync	Sync wallpaper, colors, and monitor layout to Noctalia Greeter

Media / UI

Command	Description
notification-show <summary> <body...>	Show an internal Noctalia notification
notification-clear-active	Dismiss all currently active notifications
notification-clear-history	Clear notification history
notification-dnd-set <state>	Set notification Do Not Disturb state
notification-dnd-status	Print notification DND state
notification-dnd-toggle	Toggle notification DND
notification-invoke-latest	Invoke the default action of the most recent active notification
clipboard-copy <text>	Copy text to the clipboard
clipboard-text	Print the most recent clipboard text
clipboard-clear	Clear clipboard history
wallpaper-set [connector] <path>	Set wallpaper for all or a specific output (persisted)
wallpaper-next [connector]	Switch to the next wallpaper immediately
wallpaper-previous [connector]	Switch to the previous wallpaper immediately
wallpaper-random [connector]	Switch to a random wallpaper immediately
wallpaper-get [connector]	Print default wallpaper path, or effective path for an output
theme-mode-set <mode>	Set theme mode and persist to settings.toml
theme-mode-toggle	Toggle theme mode between dark and light
theme-mode-get	Print the current resolved theme mode
color-scheme-set <{builtin|wallpaper|community|custom}> ...	Set palette source and selection in settings.toml
color-scheme-get	Print active color scheme: <source> <name>
screenshot-region	Start an interactive region screenshot
screenshot-fullscreen [mode]	Capture the focused monitor by default, pick interactively, or all outputs
screenshot-annotate	Freeze the screen and annotate it, then copy or save
annotate [path]	Draw on the screen over running apps, or annotate an image file; press F or the Freeze button to capture the background

System Controls

Command	Description
volume-up [step]	Increase speaker volume
volume-down [step]	Decrease speaker volume
volume-set <value>	Set speaker volume
volume-mute	Toggle speaker mute
volume-osd [value]	Show the volume OSD without changing volume
mic-mute	Toggle microphone mute
mic-volume-up [step]	Increase microphone volume
mic-volume-down [step]	Decrease microphone volume
mic-volume-set <value>	Set microphone volume
mic-volume-osd [value]	Show the microphone volume OSD
brightness-up [target] [step]	Increase brightness (defaults to current monitor)
brightness-down [target] [step]	Decrease brightness (defaults to current monitor)
brightness-set [target] <value>	Set brightness (defaults to current monitor)
brightness-osd <value>	Show brightness OSD without changing brightness
brightness-list-backlight-devices	List available sysfs backlight device names
keyboard-backlight-up	Increase all keyboard backlights by one level
keyboard-backlight-down	Decrease all keyboard backlights by one level
keyboard-backlight-toggle	Toggle all keyboard backlights on/off
keyboard-backlight-set <value>	Set all keyboard backlights (0-100 percentage)
keyboard-backlight-osd <value>	Show keyboard backlight OSD without changing brightness
keyboard-layout-cycle	Switch to the next keyboard layout
network-toggle	Disconnect the active network, or reconnect when nothing is connected
wifi-toggle	Toggle Wi-Fi
wifi-enable	Enable Wi-Fi
wifi-disable	Disable Wi-Fi
wifi-status	Print Wi-Fi state
bluetooth-toggle	Toggle Bluetooth
bluetooth-enable	Enable Bluetooth
bluetooth-disable	Disable Bluetooth
bluetooth-status	Print Bluetooth state
power-cycle [direction]	Step through UPower's ordered profile list, forward by default (wraps)
power-set <profile>	Set the UPower power profile (e.g., performance, balanced, power-saver)
caffeine-toggle	Toggle caffeine (idle inhibitor)
caffeine-enable	Enable caffeine (idle inhibitor)
caffeine-disable	Disable caffeine (idle inhibitor)
dpms-on	Turn monitors on
dpms-off	Turn monitors off
effects-profile-set <kind> <profile>	Set the EasyEffects output or input profile
log-level-set <level>	Set the console log level
log-level-status	Print the current console log level
session <action>	Run a built-in session action (e.g., lock, lock-and-suspend)
config-reload	Reload the config file
status	Print current state as JSON
taskbar-cycle <direction>	Step to the adjacent task or workspace group in the invoking taskbar
templates-apply	Apply configured theme templates for the current palette
osd-toggle	Toggle OSD popups
osd-enable	Enable OSD popups
osd-disable	Disable OSD popups
plugin <author/plugin:entry> <target[:bar-name]> <event> [payload]	Dispatch an event to a plugin entry
plugins <{list|enable|disable|update|source}> ...	Manage plugins and sources (list/enable/disable/update, source list/add/remove)

---

Configuration Files

~/.config/noctalia/config.toml

Main configuration file for runtime and persisted settings.

Live config (tracked in repo):

[shell]
polkit_agent = true

[wallpaper]
directory = "/home/blank/.local/share/noctalia/wallpapers"

~/.local/state/noctalia/settings.toml

Settings GUI configuration (bar widgets, theme, wallpaper automation, plugins). Note the location: ~/.local/state/, not ~/.config/.

Location: ~/.local/state/noctalia/settings.toml Status: Tracked in repo — dotfiles/noctalia/.local/state/noctalia/settings.toml; the Settings GUI rewrites the live file, so deploy adopts divergents. Bar layout lives in [bar.default]: center = [ "taskbar", "cat" ], end = [ "notifications", "clipboard", "network", "bluetooth", "tray", "battery", "session", "control-center", "clock" ]. The taskbar widget lists open windows of the focused workspace (added 2026-10-09). Apply changes with noctalia msg config-reload.

~/.config/noctalia/palettes/

Custom palette folders.

Live config (tracked in repo):

• ~/.config/noctalia/palettes/Gruber Red.json → /home/blank/.omp/dotfiles/noctalia/.config/noctalia/palettes/Gruber Red.json

Usage:

noctalia msg color-scheme-set custom "Gruber Red"

Custom palettes are folder-based and immune to the community-palette catalog sync mechanism.

~/.config/niri/noctalia.kdl

Niri-specific integration file (generated by Noctalia, untracked in repo). Contains theme colors (live: #f43841 red theme), layer rules, and wallpaper backdrop rules.

---

Niri Integration

Noctalia is deeply integrated with the Niri compositor configuration.

Autostart

File: ~/.config/niri/cfg/autostart.kdl

spawn-at-startup "noctalia"

Window Rules

File: ~/.config/niri/cfg/rules.kdl

// Geometry and clipping
window-rule {
    geometry-corner-radius 20
    clip-to-geometry true
}

// Floating settings window
window-rule {
    match app-id="dev.noctalia.Noctalia"
    open-floating true
    default-column-width { fixed 1080; }
    default-window-height { fixed 920; }
}

// Wallpaper backdrop
layer-rule {
    match namespace="^noctalia-wallpaper"
    place-within-backdrop true
}

// Panels and overlays
layer-rule {
    match namespace="^noctalia-(bar-[^\"]+|notification|dock|panel|attached-panel|osd)$"
    background-effect {
        xray false
    }
}

Keybindings

File: ~/.config/niri/cfg/keybinds.kdl

Keybind	Action	IPC Command
Mod+Shift+Return	Wallpaper panel	noctalia msg panel-toggle wallpaper
Mod+S	Control center	noctalia msg panel-toggle control-center
Mod+Shift+S	Settings	noctalia msg settings-toggle
Mod+D	App launcher	noctalia msg panel-toggle launcher
Mod+ALT+L	Lock screen	noctalia msg session lock
Mod+Shift+Q	Session menu	noctalia msg panel-toggle session
Mod+V	Clipboard history panel	noctalia msg panel-toggle clipboard
Alt+Tab	Window switcher (app icons + titles)	noctalia msg window-switcher
XF86AudioRaiseVolume	Volume up	noctalia msg volume-up
XF86AudioLowerVolume	Volume down	noctalia msg volume-down
XF86AudioMute	Mute	noctalia msg volume-mute
XF86AudioMicMute	Mic mute	noctalia msg mic-mute
XF86AudioNext	Next track	noctalia msg media next
XF86AudioPrev	Previous track	noctalia msg media previous
XF86AudioPlay	Play	noctalia msg media play
XF86AudioPause	Pause/stop	noctalia msg media stop
XF86MonBrightnessUp	Brightness up	noctalia msg brightness-up
XF86MonBrightnessDown	Brightness down	noctalia msg brightness-down
Mod+Shift+ESCAPE	Show hotkey overlay	niri show-hotkey-overlay

Recommended IPC binds (from docs):

• Mod+Space — Launcher
• Mod+S — Control center
• Mod+Comma — Settings
• Alt+Tab — Window switcher (hold)

Wallpaper Backdrop

The wallpaper layer is placed in the backdrop:

File: ~/.config/niri/cfg/rules.kdl

layer-rule {
    match namespace="^noctalia-wallpaper"
    place-within-backdrop true
}

Background Color

File: ~/.config/niri/cfg/layout.kdl

layout {
    background-color "transparent" // <- needed for noctalia-shell to set wallpaper
}

Per-Widget Layer Namespaces

Widgets use namespace-based layer rules:

layer-rule {
    match namespace="^noctalia-(bar-[^\"]+|notification|dock|panel|attached-panel|osd)$"
    background-effect {
        xray false
    }
}

Laptop / Lid Policy

File: ~/.config/niri/cfg/keybinds.kdl

Mod+ALT+L hotkey-overlay-title="Lock Screen: noctalia lock" { spawn-sh "noctalia msg session lock"; }

File: ~/.config/niri/cfg/autostart.kdl

// Lid close policy (optional)
switch-events {
    lid-close {
        spawn "noctalia" "msg" "session" "lock-and-suspend";
    }
}

Also requires logind configuration: HandleLidSwitch=ignore in /etc/logind.conf.

---

Theme / Palette Workflow

Builtin Themes

# List available builtin themes
noctalia msg theme-mode-get

# Set a builtin theme
noctalia msg theme-mode-set dark
noctalia msg theme-mode-set light

# Toggle between dark and light
noctalia msg theme-mode-toggle

Community Palettes

# Set a community palette by ID
noctalia msg color-scheme-set community "Palette Name"

Custom Palettes

# Set a custom palette from a folder
noctalia msg color-scheme-set custom "Gruber Red"

Custom palettes live in ~/.config/noctalia/palettes/ and are immune to the community-palette catalog sync.

Apply templates:

noctalia msg templates-apply

---

Dependencies

Package	Purpose	Version on blankpad (2026-10-21)
noctalia (Qt)	the shell: bar, widgets, noctalia msg	5.3.0-1.1
qt6-base	Qt6 runtime	6.12.0-3.1
niri	Wayland compositor	26.04-1.1
polkit	PolicyKit integration	128-1.1
imagemagick	image processing for palette wallpapers	7.1.2.34-2.1
ffmpeg	media processing	2:9.0.2-2.1

Three rows this page used to claim are not installed, verified with pacman -Q and command -v: wlr-randr (display information is niri msg outputs — no package needed, and displays owns that procedure), qt6-multimedia (audio reaches PipeWire through noctalia's own dependency), and brightnessctl (/sys/class/backlight/amdgpu_bl1 exists and nothing on this box drives it — laptop brightness is a gap to close, not a feature to document). A dependency table is a claim about the machine: check it before writing it.

---

See Also

• niri — Compositor configuration
• displays — Display layout
• cachyos — Operating system documentation
• noctalia msg --help — Full command reference