WBINDKEYS(1) General Commands Manual WBINDKEYS(1)

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

wbindkeys [-d]

wbindkeys permissions --check | --set

wbindkeys service --install | --uninstall

wbindkeys record [-o file]

wbindkeys man [--install]

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.

The options are as follows:

, --debug
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.
, --help
Print a summary of options and exit.
, --version
Print the version and exit.

--check
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.
--set
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.
--install
Install wbindkeys as a service that starts when you log in, using the service manager the system runs, then enable and (re)start it. The service runs the binary this command was invoked as, so run it again after moving the binary. Run it as your normal user, not as root.

Only systemd(1) on Linux is supported for now, where this writes a user unit to $XDG_CONFIG_HOME/systemd/user/wbindkeys.service. On other systems it prints that the system is not supported yet and exits with status 1.

--uninstall
Stop and disable the service and remove what service --install set up.
[-o file]
Record every key press, mouse button and scroll that wbindkeys sees, what it made of each one and which binding it would run, until . Use it when a key combination doesn't do what you expect, and attach the file to a bug report.

The recording is written to wbindkeys-recording.txt, or to the file given with -o, --output. It starts with the wbindkeys version, the system, the desktop, the keyboard layout settings, the input devices and the bindings in your configuration (without their commands), followed by one line per event. Everything typed while recording is saved, so don't type passwords.

[--install]
Print this manual page. With --install, write it to ../share/man/man1/wbindkeys.1 relative to the wbindkeys binary instead, e.g. ~/.cargo/share/man/man1 after cargo install or ~/.local/share/man/man1 after make install. man(1) looks there automatically for programs in ~/.cargo/bin or ~/.local/bin on your PATH, so no MANPATH changes are needed.

The configuration is a Lua script. Bindings are created with the () 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.

A binding runs as soon as its combination is pressed. An optional third argument changes when it runs:

Run once every key of the combination has been released, provided no other key was pressed in between. Use it for commands that send key presses of their own, such as ydotool(1), so the keys still held for the combination aren't added to them, or to bind a modifier tapped on its own without running it for every combination that uses that modifier.
Run as soon as the combination is pressed; the default.

A combination can have both a press and a release binding. For example:

bind("ALT+1", "ydotool key 125:1 2:1 2:0 125:0", { on = "release" })
bind("MOD", "wofi --show drun", { on = "release" })

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

Modifiers
ALT, CTRL, SHIFT, MOD (the Super key), SPACE, and the one-sided LEFTALT, LEFTCTRL, LEFTSHIFT, LEFTMOD, RIGHTALT, RIGHTCTRL, RIGHTSHIFT, RIGHTMOD. ALT, CTRL, SHIFT and MOD match the key on either side of the keyboard; the LEFT and RIGHT names match only that side. If a combination matches more than one binding, the one-sided binding wins.
Letters, numbers and function keys
A to Z, 0 to 9, F1 to F12.
Navigation
UP, DOWN, LEFT, RIGHT, HOME, END, PAGEUP, PAGEDOWN, INSERT, DELETE.
Other keys
ESCAPE, ENTER, BACKSPACE, TAB, BACKTICK, COMMA, PERIOD, SLASH, BACKSLASH, SEMICOLON, QUOTE, DASH, EQUAL, LEFTSQUARE, RIGHTSQUARE.
Mouse
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.

Directory the configuration file is read from; see FILES.

$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.
$XDG_CONFIG_HOME/systemd/user/wbindkeys.service
systemd user unit written by service --install on Linux.

0
Success, or permissions --check found no problems.
1
--check found a problem, permissions --set failed, service failed or is not supported on this system, or man --install could not write the page.
2
Invalid command line arguments.

Debug a configuration (stop the service first so it doesn't also react):

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

Grant access to input devices when wbindkeys is in ~/.local/bin:

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

Check access:

wbindkeys permissions --check

Start wbindkeys automatically when you log in:

wbindkeys service --install

Record what happens when a key combination doesn't work, to attach to a bug report:

wbindkeys record

Install this manual page after cargo install wbindkeys:

wbindkeys man --install
man wbindkeys

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

Divan Visagie <me@divanv.com>

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