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

# Noctalia Shell

Noctalia is a native, minimal desktop environment for the [Niri](niri/index.md) 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:

```bash
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):**

```toml
[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:**
```bash
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`

```kdl
spawn-at-startup "noctalia"
```

### Window Rules

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

```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`

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

### Background Color

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

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

### Per-Widget Layer Namespaces

Widgets use namespace-based layer rules:

```kdl
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`

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

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

```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

```bash
# 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

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

### Custom Palettes

```bash
# 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:**

```bash
noctalia msg templates-apply
```

---

## Dependencies

| Package | Purpose |
|---------|---------|
| `noctalia` (Qt) | Native desktop environment |
| `qt6-base` | Qt6 runtime |
| `qt6-multimedia` | Multimedia support |
| `niri` | Wayland compositor |
| `wlr-randr` | Display information |
| `brightnessctl` | Brightness control |
| `imagemagick` | Image processing |
| `ffmpeg` | Media processing |
| `polkit` | PolicyKit integration |

---

## See Also

- [[niri|niri/index.md]] — Compositor configuration
- [[displays|displays]] — Display layout
- [[cachyos|cachyos]] — Operating system documentation
- [`noctalia msg --help`](https://github.com/Noctalia/noctalia) — Full command reference