wl-kbptr, keyboard-driven pointer control on Wayland compositors

The Wayland gap that made this necessary

wl-kbptr is short for Wayland Keyboard Pointer, and it is a utility to help move the mouse pointer with the keyboard.

The reason it exists is a consequence of how Wayland works. Under X11 a user could bind a key to move the pointer to a screen coordinate, and tools for the keyboard-driven pointer were common. Wayland deliberately does not expose that, and a compositor implements pointer control only through specific protocols. So a user of a tiling Wayland compositor who wants to place the pointer precisely has to move the mouse by hand.

That is the problem wl-kbptr addresses, and its approach is worth understanding because it is not a simple key to coordinate binding. The program overlays its own interface on the screen and lets you narrow down an area until the target is unambiguous, then acts on the centre of that area.

The protocol requirements are the hard constraint. It needs wlr-layer-shell-unstable-v1 to display on top of other windows, and wlr-virtual-pointer-unstable-v1 to actually control the mouse pointer. A third protocol, wlr-screencopy-unstable-v1, is optional and only needed for automatic target detection in the floating mode.

The consequence is a compatibility table that is worth reading before anything else. Sway, Hyprland, niri, dwl and labwc are all listed as tested and working. Wayfire works but with a known problem, where the pointer does not move to the right location with multiple display outputs, tracked as issue 56. KWin is marked with a warning, because KDE does not support the virtual pointer and screencopy protocols, though it can still work with the --print-only option and the pointer then moved with ydotool or similar. Mutter is listed as not working at all, since GNOME supports none of the required protocols.

The four selection modes and how they chain

There are four modes for selecting a target, plus a mode that acts on it, and they can be chained through the modes configuration field.

The floating mode uses arbitrary selection areas that the user passes through standard input, with each line defining an area in the wxh+x+y format. So the area is given by width, height and an offset, and the program picks the centre of it. Areas can also be detected automatically by setting mode_floating.source to detect, for example with wl-kbptr -o modes=floating,click -o mode_floating.source=detect. That detection needs the binary built with the opencv feature and the compositor supporting screencopy. The README is candid about the cost: OpenCV is a 100 MB or more dependency, it does not noticeably change the size of the program itself, and it is optional precisely so the program can stay small. Most distributions package it with the option enabled, and you can check your own binary with wl-kbptr --version, which prints opencv when supported.

The tile mode displays a grid and you type the label of the tile you want, which is fast and predictable for a known layout.

The bisect mode narrows a given area by halving it, and at any point the cursor can be moved to the red marker position by pressing Enter or Space. The split mode narrows an area by successive splits with the arrow keys.

Both bisect and split support clicking. A left, right or middle click is made with the g, h and b keys on a QWERTY layout, and the README notes that other layouts use the same key positions, so i, d and x on Dvorak.

The click mode simply triggers a click in the middle of the selection area.

The chaining is what makes these usable. The example given is wl-kbptr -o modes=tile,bisect, which picks a region with the grid and then narrows within it. And the README points out a safety net: if you select the wrong area, you can always go back one step with the Backspace key, and this works between modes too.

The drag flag and what it is actually for

The --drag flag, or -d, changes the action from a single click to a click-and-drag between two selected positions, and it is designed to work with any mode chain. It requires two selections, and the difference between them is the useful detail.

The first selection's left-center is stored as the drag start point, a marker is drawn at that position, and the selection resets so you can pick again. The second selection's right-center becomes the drag end point. The pointer then presses and holds the left button at the start, moves to the end, and releases.

Using the left edge of the first selection and the right edge of the second is what makes text selection practical. To select a word or line you place the first selection at the beginning and the second at the end, and because the anchors are the outer edges of the areas rather than their centres, the drag spans from the start of the first to the end of the second. The README names the two uses directly, selecting text and dragging interface elements, and the latter covers sliders, scrollbars and windows that need a drag rather than a click.

This is a small feature that shows the design is aimed at real desktop use rather than a demo. A pointer control utility that could only click would be of limited value to anyone who cannot use a mouse precisely, and drag is where the value concentrates.

Installing it across distributions

wl-kbptr is packaged for several distributions, and the README gives instructions for each.

Arch Linux has an AUR package. The recommended way is to clone the AUR repository and build with makepkg, which pulls in the required files:

git clone https://aur.archlinux.org/wl-kbptr.git
cd wl-kbptr
makepkg -si

If you only want the PKGBUILD, the README gives a curl command that fetches it from the AUR cgit interface, followed by makepkg -si.

NixOS has a wl-kbptr package, and the README notes that Nix can also be used to install it on other distributions, which is the practical route for anyone not on a distribution with a native package.

Chimera Linux has the package in its contrib repository, installed with apk add chimera-repo-contrib followed by apk add wl-kbptr.

Fedora carries the package in the official repository:

dnf in wl-kbptr

That command has a typo in the README, dnf in rather than dnf install, and it is worth knowing because a copy-paste will fail.

Building from source uses Meson, and the README gives the release build:

meson setup build --buildtype=release

The repository top level shows the layout of the source tree: src/ for the C code, protocol/ for the Wayland protocol definitions, share/ for data files, helpers/, a meson.build and meson.options, a config.example configuration file, and a .clang-format file. There is also a LICENSE-NTP file alongside the main LICENSE, which suggests some part of the code carries separate terms.

What this replaces, and what it does not

The alternatives for keyboard pointer control on Linux are worth naming plainly.

ydotool is the tool the README points to for the KWin case. It works at a lower level, by driving the uinput device and injecting events, which means it is not limited to compositors that implement the virtual pointer protocol. The trade-off is that it needs root privileges to write to the input device, it has no area selection interface, and it moves the pointer by absolute coordinates rather than by helping you identify a target.

There is also the compositor-native route. Hyprland, Sway and niri all have their own scripting and binding capabilities, so a user who is comfortable writing a compositor script can bind keys to move the pointer without any additional program. That is a reasonable answer for a fixed set of positions and a poor answer for pointing at something arbitrary on screen.

wl-kbptr's difference in approach is that it is a target picker rather than a coordinate entry system. You are asked to identify a region of the screen rather than to know a coordinate, which suits a person who cannot see well enough to aim but can describe roughly where something is.

The limits are equally clear. It needs wlr-layer-shell and wlr-virtual-pointer, so the GNOME desktop is out, and KDE is only partly supported. The Wayfire multi-monitor problem is a live bug rather than a design decision. And the optional OpenCV dependency for detection is heavy enough that the README treats it as a separate build option.

On maintenance, the releases are v0.3.0 in April 2025, v0.4.0 in July 2025 and v0.4.1 in November 2025, with the last push on 2026-10-01. The GPL-3.0 licence is the other thing to note, since it is copyleft and therefore a constraint if you were thinking of vendoring the source into a proprietary product.

Editorial conclusion

Adopt wl-kbptr if you run Sway, Hyprland, niri, dwl, labwc or Wayfire and want pointer control from the keyboard, including a drag mode for selecting text and moving interface elements. Do not adopt it if your compositor is GNOME Mutter, which supports none of the required protocols, or if you are on KDE and want real pointer movement rather than printed coordinates you feed to another tool. Verify first by running wl-kbptr --version to see whether the opencv feature is compiled in, then by trying the tile mode on a single screen before chaining modes.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. moverest/wl-kbptr on GitHub
4. README
5. Releases