warpd

Run warpd in normal mode

$ warpd --normal

$ warpd --hint

$ <h>

$ <j>

$ <k>

$ <l>

$ <m>

warpd [OPTIONS]

--config FILE
    Specify an alternative configuration file to load instead of the default.

--verbose
    Enable verbose logging output to the console for debugging purposes.

--version
    Display the version information of warpd and exit.

warpd is a minimalist, keyboard-driven mouse control daemon for Linux, primarily designed for Wayland compositors. It enables users to manipulate the mouse cursor, perform clicks, and scroll entirely through keyboard shortcuts. It operates by interacting with the libinput library to simulate mouse events, making it a valuable tool for keyboard-centric workflows, tiling window manager users, or individuals seeking to minimize mouse usage.

Unlike some other tools, warpd doesn't provide its own hotkey daemon; instead, it relies on external tools like sxhkd to bind keyboard shortcuts that trigger warpd's actions (e.g., move cursor, click, scroll). Its highly configurable nature is primarily managed through a TOML configuration file, typically located at ~/.config/warpd/config.toml, allowing users to customize speeds, acceleration, and various operational modes.

Primarily for Wayland: warpd is designed for Wayland compositors, leveraging libinput. While libinput also works on X11, warpd's full functionality and intended use are strongly tied to Wayland.

No Built-in Hotkey Daemon: It does not include its own hotkey daemon; relies on external tools (e.g., sxhkd) for keybinding management.

Config File Driven: Configuration is extensively done via a TOML file (~/.config/warpd/config.toml), not directly through command-line arguments for most features.

warpd is highly configurable via its TOML configuration file, typically located at ~/.config/warpd/config.toml. This file allows users to define cursor movement speeds, acceleration profiles, and enable various advanced mouse actions like 'normal mode', 'hint mode', 'grid mode', and 'screen warp'. These actions can then be mapped to keyboard shortcuts using an external hotkey daemon.

Unlike many tools that directly intercept keyboard input, warpd follows a design philosophy of separation of concerns. It does not handle keyboard input for triggering actions itself. Instead, it expects to receive commands (e.g., via stdin or a socket) from an external hotkey daemon like sxhkd. This design allows for seamless integration into existing user keybinding setups and avoids conflicts with other input tools.

Beyond basic cursor movement, warpd supports several powerful modes to enhance keyboard navigation:

Hint Mode: Similar to browser extensions like Vimium, it displays clickable labels on screen elements, allowing direct selection via keyboard.

Grid Mode: Divides the screen into a precise grid, enabling users to rapidly jump the cursor to specific screen regions.

Screen Warp: Allows direct warping of the cursor to a specific monitor or screen edge.

These modes significantly expand the utility of keyboard-driven mouse control.

warpd was created to provide a lightweight, keyboard-driven mouse control solution specifically for Wayland compositors, addressing the limitations of traditional X11-based tools like xdotool or keynav in the Wayland ecosystem. Its development emphasizes minimalism and robust input handling through libinput, filling a critical gap for keyboard-centric users transitioning to Wayland environments. It is an open-source project, continuously developed and typically available through distribution repositories or directly from its source code.

sxhkd(1), xdotool(1), keynav, libinput(4)