warpd(1)

📦 version 1.3.5, in nixos 26.05, nixpkgs unstable

💅 warpd(1) — General Commands Manual 💅

okay so bestie, this is the General Commands Manual page for warpd, and honestly? it's a whole lifestyle. buckle up, we're going through every single flag together and i'm not skipping a crumb 🍓

🌸 DESCRIPTION 🌸

literally just: a modal keyboard driven pointer manipulation program. that's her. that's the whole thing. your mouse could never 💅

✨ SYNOPSIS ✨

warpd [options]

🎀 OPTIONS 🎀

the classic starter pack — no cap, here's everything:

  • -f, --foreground — runs warpd in the foreground. mainly useful for debugging 👀
  • -l, --list-keys — prints out a list of all the valid keys that you're allowed to use as config values. very helpful when you're like "is this even a key"
  • --list-options — prints all the configurable options. the full menu, bestie 🍓
  • -v, --version — prints the current version ✨
  • -c, --config <config file> — use the config file you provide. and - corresponds to stdin, iykyk

🎮 Mode Flags 🎮

  • --hint — run warpd in (daemonless) hint mode
  • --hint2 — run warpd in 2 stage hint mode
  • --grid — run warpd in grid mode
  • --normal — run warpd in normal mode
  • --history — run warpd in history hint mode
  • --oneshot — when you pair this with one of the mode flags, warpd exits as soon as the mode is complete (i.e. it doesn't drop into normal mode). and when it's used with normal mode, it exits as soon as a mouse button is pressed (without actually pressing it 💀). if you don't specify any mode flag, the default behaviour is the same as --normal --oneshot. principally useful for scripting, fr fr
  • -q, --query — consumes a list of hints from stdin and prints the result to stdout (in the form <x> <y> <hint>). each line should have the form <label> <x> <y>. may be used in conjunction with --click 🫶
  • --drag — automatically starts a drag operation when paired with --normal
  • --move '<x> <y>' — move the pointer to the specified coordinates and exit. iconic, no notes
  • --click <button> — sends a mouse click corresponding to the button you supplied, then exits. may be paired with --move or --oneshot (in which case the click occurs at the end of the selection) 🖱️
  • --record — when used with --click, this adds the click event to warpd's history. she remembers 🌸

🔥 DESCRIPTION (the full lore) 🔥

warpd has three main modes which can be used to manipulate the pointer, and you're gonna learn all three. the primary mode is called 'normal mode' (A-M-c) and it facilitates local pointer movement using vi-like bindings (h j k l). the other two modes — hint and grid mode — are used to effect larger movements across the screen, and they're expected to be used in combination with normal mode to achieve the desired end ✨

for example, the user might activate warpd in hint mode (A-M-x) to pinpoint the start of a text region before starting a drag operation (v) and ultimately using normal mode to complete the selection. and if the selection is a large body of text, it may be desirable to activate grid (g) or hint (x) mode for a second time to warp the pointer to the desired region's terminal point 👑

in its simplest form, warpd can be used as a poor man's xdotool (--move/--click). humble queen behaviour 💅

a description of each mode follows (see also USAGE_NOTES):

🌈 Normal Mode (A-M-c) 🌈

this is the default mode (and the endpoint of both grid and normal mode) and it's designed for short distance pointer manipulation. it's particularly useful for manipulating popup menus and selecting text (see Dragging). the default behaviour is vi-like. pressing the mapped directional keys (default hjkl) moves the cursor in a continuous fashion, but the pointer can also be warped to the edges of the screen using the home (H), middle (M), and last (L) mappings. finally, a numeric multiplier can be supplied to the directional keys as an input prefix in order to move the cursor by a proportional increment in the given direction (e.g. 10j moves 10 units down) 🔢

🦋 Hint Mode (A-M-x or simply 'x' within normal mode) 🦋

this mode populates the screen with a list of labels and lets the user immediately warp the pointer to a given location by pressing the corresponding key sequence. it's similar to functionality provided by browser plugins like Vimperator, but it works outside of the browser and indiscriminately covers the entire screen. once a target has been selected, 'normal mode' is entered for further manipulation 💖

Note: while it may at first be tempting to saturate the screen with hints, the user is cautioned against this. a balance must be struck between hint size, the number of hints, and the size of the screen. enough space must be left to provide contextual awareness, while enough hints must be present to facilitate targetting UI elements without the need for too much adjustment. once this equilibrium has been achieved, using hint mode become second nature and is (in the author's opinion) superior to grid mode for quickly pinpointing elements 👑

for finer movements, a two phase hint mode can be activated by pressing X within normal mode. yes, capital. yes, it matters 🎀

🧚 History Mode (';' within normal mode) 🧚

identical to hint mode but it exclusively displays hints over previously selected targets. the way that she remembers where you've been 😭💜

⭐ Grid Mode ('A-M-g' or simply 'g' within normal mode) ⭐

by default grid mode divides the screen into a 2x2 grid. each time a key is pressed the grid shrinks to cover the targeted quadrant. the cursor is placed in the middle of the grid ✨

covers the desired target a mouse button (e.g. m) can be pressed.

E.G

             +--------+--------+            +--------+--------+
             |        |        |            |  u |  i |       |
             |   u    |   i    |            |----m----+       |
     M-x     |        |        |     u      |  j |  k |       |
    ----->   +--------m--------+   ----->   +---------+       |
             |        |        |            |                 |
             |   j    |   k    |            |                 |
             |        |        |            |                 |
             +--------+--------+            +--------+--------+

🌸 Screen Selection Mode ('A-M-s' or simply 's' within normal mode) 🌸

this mode is intended for multi-screen setups and provides the user with a dedicated set of hints for switching monitors and dropping them into normal mode 🖥️🖥️

🫶 Dragging 🫶

pressing v whilst in normal mode toggles a drag operation. the cursor can then be warped around the screen as normal in order to select text or move objects, until the drag key is hit again or a mouse button is pressed. additionally, the copy_and_exit key (c) may be used to copy the selected text to the system clipboard and terminate the current session 📋✨

💀 Wayland 💀

Wayland's architecture does not allow clients to globally bind hotkeys. in order to run warpd, one of the mode flags must be used. these can be bound to the corresponding hotkeys in your compositor 👀

E.G

on sway:

bindsym Mod4+Mod1+x exec warpd --hint
bindsym Mod4+Mod1+c exec warpd --normal
bindsym Mod4+Mod1+g exec warpd --grid

non-wayland users should favour the daemon, since it also caches some of the draw operations to improve performance 🚀

🎀 CONFIG OPTIONS 🎀

the program can be modified by placing configuration options in ~/.config/warpd/config, and a complete list of which can be obtained with --list-options 📝

each option must be specified on its own line and have the format:

<option>: <value>

💅 RULES 💅

  • options which expect one or more keys may be specified multiple times, in which case all accepted mappings are interchangeable.
  • options which accept multiple keys (e.g. buttons) expect each key to be separated by a space.
  • for options expecting only a single key, it's possible to specify all desired bindings as space separated values in a single declaration.
  • if a key is bound to multiple config options, the most recently defined one takes precedence. newest wins, periodt 👑

🍓 E.G 🍓

hint_mode: f a

is identical to

hint_mode: f
hint_mode: a

and will bind both f and a to hint mode activation keys ✨

while

buttons: m , .
buttons: j k l

will bind both the sequences m , . and j k l to mouse buttons 1 2 and 3 respectively. note that the latter set of bindings override the default normal mode movements keys — so yeah, that's a real tradeoff, bestie 😭

🌈 SCRIPTING 🌈

judicious use of warpd's flags makes creating custom modes fairly easy 🛠️

for example, the --oneshot flag may be used in conjunction with one of the mode flags to facilitate target selection, at which point subsequent action can be taken by the script 🔥

🦋 Examples 🦋

# Prompt the user for a target using two stage hint mode and
# left click on the result.
#
# This particular example can be achieved more concisely with:
#
# warpd --hint2 --click 1

warpd --hint2 --oneshot; warpd --click 1
# Interactively create a hint file.
#
# Points can be added by navigating around as usual and pressing 'p'.
# The process is terminated by using the exit key.

warpd --normal|awk '{print substr("asdfghjkl;qwertyuiopzxcv,./;", NR, 1), $0}' > hints
# Prompt the user for one of the recorded hints and click on the
# result.

warpd --click 1 --query < hints

👑 USAGE NOTES 👑

the key to using warpd effectively is learning when to exit normal mode. much of one's time at a computer is spent moving the mouse between windows, interacting with UI elements, and reading text. what one might call 'browse mode'. it is in this mode of operation that it makes sense to keep warpd active 💖

developing facility with the scroll and oneshot mouse buttons is key to achieving this. for example, if you happen to have two documents open and wish to switch between them, you can simply type x fx (where fx is a hint) if normal mode is already active. scrolling can subsequently be achieved using e and r. once you finally wish to type something, you can do x fx n to focus on the UI element, click, and exit 🎯

conversely, warpd can complement an input heavy workflow with its oneshot functionality and dedicated activation keys (E.G. n, A-M-l, A-M-x, etc) ✨

it's important to note that warpd is not intended to replace mouse heavy workflows, and will likely always be inferior for rapid precise local movements. when confronted with an IDE, or some other pointer driven abomination, the author still sometimes reaches for his mouse 💀😭

🍓 On Dragging 🍓

activating discrete mode and pressing v can provide a familiar environment to a vi user, but it's important to remember that cursor manipulation is application agnostic and consequently ignorant of the text on the screen. all movement is necessarily pixel based, consequently, drag + hint mode can be a superior method for surgically selecting text (though it may at first be less intuitive) 💅

🌸 FILES 🌸

$XDG_CONFIG_HOME/warpd/config
~/.config/warpd/config

the path of the configuration file (searched in order) 🎀

⭐ EXIT STATUS ⭐

on error warpd will exit with a status of 255, otherwise the exit code will correspond to the button used to terminate warpd (in the case of oneshot buttons or in the presence of --oneshot). if warpd is terminated explicitly (i.e. with the exit key) it will exit with a status of 0 ✨

💀 BUGS/LIMITATIONS 💀

okay bestie, real talk time 🫶 — warpd uses a bunch of platform-specific hacks to sneak around the limitations of the display server. And here's the tea: all the implementations were written by the same author, who presently uses X. So testing on non-X platforms has been minimal. YMMV (your mileage may vary, and it may vary a lot) 😭

Bugs can be reported here:

https://github.com/rvaiya/warpd/issues/

A list of known limitations follows — buckle up, it's giving ✨ caveat emptor ✨:

  • Multiscreen support currently does not support hotplugging. Which means you must restart warpd after making any changes to your screen configuration. No cap, just restart it 💅
  • For implementation reasons, the cursor position is not horizontally centered, but to the right of the actual pointer. This generally isn't an issue, but may become more noticeable as you increase cursor_size. So if your cursor's looking a little off-center at big sizes... that's why 🎀

🖥️ X

  • Unplugging the keyboard while warpd is one of its active modes will cause pandemonium 💀 If you do this (don't :P), you may need to remotely ssh into the machine or switch to a VT to kill the process. Literally the worst vibe.
  • warpd uses Xinput for input processing to bypass certain limitation of the X input system. A byproduct of this is that certain remapping tools will not work (e.g xcape). If you are in the habit of making unorthodox changes to your keymap (like remapping capslock to control/escape), you may want to try an evdev based remapper like keyd:
https://github.com/rvaiya/keyd

🍎 MacOS

  • Cursor hiding relies on a hack that some programs ignore (e.g iTerm).
  • Some programs (e.g iTerm) have a 'secure input mode' (which can usually be disabled) that causes interference.

🌊 Wayland

  • Cursor hiding doesn't work. 🫠
  • Running as a daemon doesn't work (can't listen for hotkeys).
  • UI elements (e.g input fields) which require focus can't be selected.
ngl bestie, if you're on Wayland, go in with your eyes open 👀 none of this is a surprise, it's documented, and it's all listed right here 🌸

👑 AUTHORS 👑

Written and maintained by Raheman Vaiya (2019-). See https://github.com/rvaiya/warpd for more information. absolute icon behaviour, honestly ⭐

and that's the whole page, bestie!! 🎀 this was warpd(1), source/version vibes from 2022-11-05 — go forth and warp those pointers, you gorgeous main character 💖✨🦋

📦 where this page comes from