WBINDKEYS(1) User Commands WBINDKEYS(1)

wbindkeys - bind keys, mouse buttons and scroll events to commands on Wayland

wbindkeys [-d]
wbindkeys permissions --check | --set
wbindkeys -h | -V

wbindkeys runs shell commands when key combinations, mouse buttons or scroll events are pressed. It is a Wayland replacement for xbindkeys(1), configured with a Lua script.

Input is read directly from the input devices in /dev/input through libinput rather than through the compositor, so it works the same under any Wayland compositor. Because of this, the user running wbindkeys needs read access to those devices; see PERMISSIONS below.

Run without a subcommand, wbindkeys loads its configuration and keeps running, listening for input.

Print log output to stderr: which input devices were opened (or could not be opened), the configuration file being loaded, each registered binding and the key codes it maps to, unrecognised key names, every key press with its combination, and whether it matched a binding.

Print a summary of options and exit.

Print the version and exit.

Check that the udev rule is installed and that every input device can be read by the current user. Run it as your normal user, not as root. Lists any devices that cannot be read and exits with status 1 if anything is wrong.

Install the udev rule in /etc/udev/rules.d/69-wbindkeys.rules, reload udev rules and re-trigger input devices so the current session gets access. Must be run as root.

The configuration is a Lua script. Bindings are created with the bind function, which maps a key combination to a shell command:

bind("ALT+T", "alacritty")
bind("MOD+Mouse4", "wofi --show drun")
bind("ALT+ScrollUp", "pactl set-sink-volume @DEFAULT_SINK@ +5%")

Commands are run with sh(1) and their output is discarded.

Key names are case-insensitive and joined with +. The available names are:

ALT, CTRL, SHIFT, MOD (the Super key), SPACE, and the right-hand RIGHTALT, RIGHTCTRL, RIGHTSHIFT, RIGHTMOD. ALT, CTRL, SHIFT and MOD refer to the left-hand keys.

A to Z, 0 to 9, F1 to F12.

UP, DOWN, LEFT, RIGHT, HOME, END, PAGEUP, PAGEDOWN, INSERT, DELETE.

ESCAPE, ENTER, BACKSPACE, TAB, BACKTICK, COMMA, PERIOD, SLASH, BACKSLASH, SEMICOLON, QUOTE, DASH, EQUAL, LEFTSQUARE, RIGHTSQUARE.

MOUSE1 to MOUSE10, SCROLLUP, SCROLLDOWN, SCROLLLEFT, SCROLLRIGHT.

When a binding has several modifiers they must be pressed in the order they are written. Unknown key names are ignored; run with --debug to see them.

wbindkeys runs as a normal user and needs read access to /dev/input. Running sudo wbindkeys permissions --set once installs a udev rule that tags input devices with uaccess, so systemd-logind(8) grants access to the user in the active local session. Check access with wbindkeys permissions --check.

If devices are still not readable, re-run permissions --set, or log out and back in. Access is only granted to the session at the physical seat, so it does not work over SSH.

$XDG_CONFIG_HOME/wbindkeys/init.lua
Configuration file. Defaults to ~/.config/wbindkeys/init.lua when XDG_CONFIG_HOME is not set. wbindkeys exits with an error if it does not exist.

/etc/udev/rules.d/69-wbindkeys.rules
udev rule installed by permissions --set.

~/.config/systemd/user/wbindkeys.service
systemd user service created by make install.

0
Success, or permissions --check found no problems.
1
permissions --check found a problem, or permissions --set failed.
2
Invalid command line arguments. 

systemctl --user stop wbindkeys.service
wbindkeys --debug
    

sudo ~/.local/bin/wbindkeys permissions --set
    

wbindkeys permissions --check

xbindkeys(1), libinput(4), udev(7), systemd-logind(8)

Divan Visagie <me@divanv.com>

Report bugs at https://github.com/divanvisagie/wbindkeys/issues