Frank
b441cfda56
- niri: index/config-tree rework, displays.md desk-profile rewrite, tips/action-reference/default-bindings refresh (26.04), generated keybindings.md (119 bindings) - noctalia-shell.md: settings.toml lives in ~/.local/state, taskbar widget, v5 keybind table (Mod+D/Mod+V/Alt+Tab) - handy.md: NEW; live nested store shape, fleet endpoint, known thinking-model empty-content breaker + verified cure - log.md: DE redesign entry + pam_faillock sudo-lockout incident
62 lines
2.2 KiB
Markdown
62 lines
2.2 KiB
Markdown
---
|
|
type: howto
|
|
title: Niri Tips and Gotchas
|
|
description: Practical tips for working with niri — Mod key behavior, shell expansion, config reload, vim keys, and programmatic invocation.
|
|
tags:
|
|
- niri
|
|
- tips
|
|
- gotchas
|
|
verified: 2026-10-09
|
|
---
|
|
|
|
# Helpful Tips
|
|
|
|
## 1. Mod key
|
|
|
|
Use `Mod` instead of `Super` for configs that work both on TTY and in nested windows.
|
|
|
|
## 2. No shell expansion in spawn
|
|
|
|
`spawn` does not expand `$VAR` or `~`. Use `spawn-sh` or wrap in `sh -c`.
|
|
|
|
## 3. Config reload
|
|
|
|
**Do NOT send `SIGHUP` to the niri process** (`kill -s SIGHUP $(pgrep -f 'niri --session')`) — it causes a full session logout/restart instead of a live config reload.
|
|
|
|
Correct reload options, in order of preference:
|
|
- `niri msg action load-config-file` — live reload without disrupting the session (preferred).
|
|
- Log out and back in (safe, guaranteed clean reload).
|
|
- Let the user decide when to reload; agents should modify config files without auto-reloading.
|
|
|
|
Niri reads `~/.config/niri/config.kdl` (or `config.kdl` relative to its CWD). Split config lives in `~/.config/niri/cfg/` — each `.kdl` file is `include`d from the main config, so a reload picks up edits to any included module.
|
|
|
|
### 26.04 Config Loading Features
|
|
|
|
`niri msg action load-config-file --path <file>` switches configs at runtime (26.04). It includes:
|
|
- `optional=true` support — allows loading configs that may not exist
|
|
- `~` expansion — tilde paths are expanded to the niri user's home directory
|
|
|
|
## 4. Alternative navigation
|
|
|
|
Vim-like keys (H/J/K/L) are bound by default alongside arrow keys.
|
|
|
|
## 5. Programmatic invocation
|
|
|
|
Every action can be invoked via `niri msg action <action-name>`.
|
|
|
|
### 26.04 IPC Enhancements
|
|
|
|
- `niri msg layers` — lists layer-shell namespaces per output
|
|
- `niri msg casts` — lists active PipeWire screencasts
|
|
- `Escape` cancels drag-and-drop operations
|
|
- Duplicate-bind parse errors now show the **first definition** in the file
|
|
|
|
### Pointer Behavior
|
|
|
|
Pointer warps across the screen during `view-scroll` gestures.
|
|
|
|
## Related
|
|
|
|
* [Key Bindings Syntax](/tools/niri/key-bindings-syntax.md) — Configuration details
|
|
* [Action Reference](/tools/niri/action-reference.md) — All available actions
|