Files

T

Frank ac1608e71f docs(niri): fold AGENTS.md overwrite into niri KB section

The working tree had replaced the operating contract in AGENTS.md with a
niri config-reload + keybinding-constraints note. Content relocated to its
proper home: tips.md 3-config-reload (SIGHUP footgun, load-config-file) and
key-bindings-syntax.md constraints section. AGENTS.md restored from HEAD.

2026-09-09 16:19:02 -07:00

2.1 KiB

Raw Permalink Blame History

type, title, description, tags, verified

type

title

description

Key Bindings Syntax

Key bindings go in the binds {} section of the config file (~/.config/niri/config.kdl):

binds {
    Mod+T { spawn "alacritty"; }
    Mod+Left { focus-column-left; }
}

Modifiers

Ctrl or Control
Shift
Alt
Super or Win
ISO_Level3_Shift or Mod5 (AltGr)
ISO_Level5_Shift (for lv5 options like lv5:caps_switch)
Mod — Special: equals Super on TTY, equals Alt in nested window

Bind Options

binds {
    Mod+T repeat=false { spawn "alacritty"; }     // Do not repeat on hold
    Mod+T cooldown-ms=500 { spawn "alacritty"; }  // Rate-limit
    Super+Alt+L allow-when-locked=true { spawn "swaylock"; }  // Works when locked
    Mod+Q hotkey-overlay-title="Close Window" { close-window; }  // Custom title in overlay
    Mod+Escape allow-inhibiting=false { ... }     // Always works (even with inhibitors)
}

Finding Key Names

Use wev to find XKB key names:

wev
# Then press the key you want to bind — look at `sym: XXXX` in output

Shifted keys require Shift + the unshifted key (for example, Mod+Shift+Comma for < on US QWERTY).

Constraints

One action per keybind. Each { ... } block holds exactly one action; multiple actions like { move-window-up; consume-or-expel-window-up; } are rejected at parse time.
No duplicate keys. The same key combo (e.g. Mod+CTRL+Left) can only appear once in binds {}. Adding a new binding for an existing key causes a parse error.
Valid consume/expel actions: consume-or-expel-window-left, consume-or-expel-window-right, and expel-window-from-column. The consume-or-expel-window-up/-down variants do NOT exist.

Default Key Bindings — What niri ships with out of the box
Action Reference — All available actions

2.1 KiB Raw Permalink Blame History