Binds & actions#
Grammar#
In the binds { } block, the chord is the node name and the single child node is the action:
binds {
Mod+Return { spawn "foot"; }
Mod+Q on="release" { close-window; }
Mod+F repeat=#true { toggle-fullscreen; }
Mod+minus { adjust-split-ratio "-0.1"; }
XF86AudioMute allow-when-locked=#true cooldown-ms=200 title="Mute" { spawn-sh "wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle"; }
}
(The Lua form is a table per bind; see Lua configuration.)
The default config ships a complete working set: Mod+Return terminal, Mod+D launcher, Mod+Q close, Mod+F fullscreen, Mod+Space float, focus and swap on both the arrows and Mod+H/J/K/L, Mod+Tab cycling, Mod+1..9 workspaces plus Mod+PageUp/Down relative, Mod+MouseLeft/Right pointer grabs, Print and Mod+Shift+S screenshots, audio, mic, media, and brightness keys, Mod+T layout toggle, and Mod+Shift+E quit; the remaining scrolling column verbs sit as commented examples. Writing your own binds { } block replaces the whole default set, so bring everything you want to keep.
Chords#
+-separated, case-insensitive. Modifiers: shift, ctrl (or control), alt, super (aliases meta, logo), and Mod, the placeholder that input { mod-key } resolves to super or alt, so one config works for both conventions. Exactly one non-modifier key per chord, matched against the exact modifier set: Mod+X does not fire while Mod+Shift+X is held.
Key names are evdev KEY_* names, lowercased, plus friendly aliases: return/enter, esc/escape, space, minus, letters, digits, f1..f12, arrows, xf86audiomute and its multimedia siblings, and modifier keys themselves (super_l, alt_r). Mouse buttons ride the chord too: Mod+MouseLeft, MouseSide, MouseExtra. That is how the classic mod-drag feel is built: Mod+MouseLeft { pointer-move; } and Mod+MouseRight { pointer-resize; }.
Bind properties#
| Property | Effect |
|---|---|
on="press" or on="release" | when it fires; release binds arm on press and fire once on key-up (default press) |
repeat=#true | re-fires at the keyboard repeat rate while held |
allow-when-locked=#true | still fires while the session is locked (media keys, mostly) |
cooldown-ms=200 | rate-limits the chord, 1..60000 ms |
title="Screenshot" | a label surfaced by burrow binds, for shell-drawn hotkey overlays |
Actions#
Every action is also accepted over the IPC socket, same names, by construction.
| Action | Argument | Does |
|---|---|---|
spawn | argv words: spawn "foot" "-e" "htop" | run a program directly |
spawn-sh | one string | run through /bin/sh -c |
focus-workspace | 1..n, or "+1"/"-1" | switch workspace, absolute or relative (wraps) |
move-to-workspace | number, optional focus=#false | move the focused window and follow; with focus=#false, stay |
send-to-workspace | number | move the window, stay (same as focus=#false) |
toggle-fullscreen | toggle fullscreen | |
toggle-floating | toggle floating | |
close-window | ask the window to close | |
focus-next / focus-prev | cycle focus on the workspace | |
focus-left/right/up/down | directional focus | |
swap-left/right/up/down | swap the focused window directionally; on a scrolling workspace, left/right trade it with the neighbor column's active window | |
move-column-left / -right | scrolling: leapfrog the whole focused column along the strip | |
adjust-split-ratio | "+0.1" / "-0.1" | nudge the parent split of the focused tile; on a scrolling workspace, nudge the column width |
set-layout | "dwindle" / "scrolling" / "toggle" | switch the focused workspace's layout live |
consume-or-expel-left / -right | scrolling: merge a lone window into the neighbor column, or pop a stacked one out to that side | |
cycle-column-width / cycle-column-width-back | scrolling: step the focused column through the preset-widths ladder | |
toggle-full-width | scrolling: flip the focused column to full width and back | |
center-column | scrolling: center the focused column in the view | |
pointer-move | grab the window under the cursor and let the pointer carry it; tiled windows drag-and-swap | |
pointer-resize | the same grab, resizing by the quadrant the pointer started in | |
quit | exit the compositor |
There are no silently ignored actions: an unknown action name is a config error, and reserved features error with "not implemented yet" until they land.
What you cannot rebind#
Ctrl+Alt+F1..F12 switch VTs, take precedence over any configured bind, and cannot be rebound.