KEYNAV(1)

📦
version 0.20180421~git6505bd0d · 4 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 KEYNAV(1) — the keynav girlies' manual 💖

okay so bestie, sit down, hydrate, and let me tell you about keynav — the keyboard navigation tool that's about to change your whole mouse situation. no cap. 🦋

✨ NAME ✨

keynav — keyboard navigation tool. that's it, that's the whole vibe. 💅

🌸 SYNOPSIS 🌸

keynav [optional-startup-commands]

🎀 DESCRIPTION 🎀

so like, keynav is a utility for generally operating your mouse with your keyboard. the main character usage is dividing your screen into sections and then selecting them over and over until you land exactly on the point where you want to move the mouse, or click, or whatever your heart desires. it's giving precision, honestly. 👑

you can pass any valid keynav commands to keynav from the command-line. just make sure you quote things properly, okay? the shell is not your enemy but she does not read your mind. 😭

for example, to load another config file or two:

keynav "loadconfig ~/myconfigs/keynavrc,loadconfig ~/myconfig/anotherkeynavrc"

another example — daemonize on startup:

keynav daemonize

🧚 CONFIGURATION 🧚

keynav is configured by default from a config file in your home directory, ~/.keynavrc. iconic location. very home-sweet-home. 🏠

the default configuration can be found in the "DEFAULT CONFIGURATION" section. go peek, she's cute.

'#' will delimit comments. the configuration consists mostly of binding keys to keynav commands. the following two commands must appear on lines by themselves, not as key bindings — they're too important for that, they're doing their own thing.

  • daemonize — this will make keynav background itself after parsing the config file and setting up keybindings. if there are errors during keybinding, then keynav will not background and will exit with failure. so if she's mad, she's loud about it. 💀
  • clear — this will clear all existing keybindings. this is useful if, for example, you do not want any of the default keybindings that come with keynav. a fresh start, a clean slate, a rebrand. ✨

the rest of the configuration has this format:

keybinding keynav-command[,keynav-command,...]

you can have multiple commands for a single keybinding. multitasking queen. 💅

the way to start keynav's navigation is to use the start command. additionally, any keys with start as a command will be grabbed as global hotkeys. for example, this configuration:

ctrl+semicolon start
space click 1

this will make keynav grab the ctrl + semicolon keybinding globally, but it will not grab space. the space keybinding will only be active while keynav is active — after you press a key sequence that invokes start. so space is keeping it lowkey until you call on her.

in case of a keyboard layout where semicolon is just reachable by pressing Shift, the activation key combination actually might not be ctrl+shift+[other character], but just ctrl+[other character], e.g. ctrl+comma instead of ctrl+shift+comma on Swiss-German or German-German layouts. layouts are chaotic like that, no cap. 🌈

if you aren't sure what the name of your key is, you can run xev(1) and press each key you want to learn about while the xev window has focus. the output will include the keysym name (like Shift_L, or Return, etc). free key lore. 🍓

moving on, here are all the keynav commands you can use:

✂️ CUTS AND MOVES ✂️

movements are bounded by screen edges. see "SCREEN EDGES" for edge and multiple screen handling. she stays in her lane, literally. 🛑

  • cut-up [value] — this will cut the keynav window upwards. we will shrink from the bottom upwards. the default cut value, if not specified, is 0.5. see "CUT AND MOVE VALUES" for what this value means.
  • cut-down [value] — this will cut the keynav window downwards. we will shrink from the top down. the default cut value, if not specified, is 0.5. see "CUT AND MOVE VALUES" for what this value means.
  • cut-left [value] — this will cut the keynav window leftwards. we will shrink from the right to the left. the default cut value, if not specified, is 0.5. see "CUT AND MOVE VALUES" for what this value means.
  • cut-right [value] — this will cut the keynav window rightwards. we will shrink from the left to the right. the default cut value, if not specified, is 0.5. see "CUT AND MOVE VALUES" for what this value means.
  • move-up [value] — this will move the window up. the default value, if not specified, is 1. see "CUT AND MOVE VALUES" for what this value means.
  • move-down [value] — this will move the window down. the default value, if not specified, is 1. see "CUT AND MOVE VALUES" for what this value means.
  • move-left [value] — this will move the window left. the default value, if not specified, is 1. see "CUT AND MOVE VALUES" for what this value means.
  • move-right [value] — this will move the window right. the default value, if not specified, is 1. see "CUT AND MOVE VALUES" for what this value means.
  • cursorzoom width height — this command centers the keynav window on the mouse position and sets the window size to the given width and height (in pixels). zoom zoom. 🔍
  • windowzoom — this command makes the keynav window fit the current application window. this is useful if you have your windows in a tiled arrangement. so organized, so demure. 🫶

🔲 GRID COMMANDS 🔲

  • grid [COLUMNSxROWS] — the default grid is 2x2. if you want more grid cells you can choose any number of columns and rows. go wild, bestie.
  • grid-nav [on OR off OR toggle] — grid navigation is off by default. when turned on, every grid cell will have a two-letter label. to select a single cell, you simply type the two letters. the toggle value will toggle grid-nav. it's giving keyboard shortcuts for your own screen. 💅
  • cell-select [value] — cell selection is similar to grid-nav, but less visual. you would bind keys to select specific cells. with cell-select, there are no labels.

the value can be one of two formats. first, the COLUMNxROW syntax. cell-select 3x1 will select column 3, row 1. the second format is simply a number. the number represents the counting of the cell, starting at the top left and working right.

a visual might help. with grid 3x3 the following is used with cell-select:

 +----------------------------------------------+
 |              |               |               |
 |     1x1      |      2x1      |      3x1      |
 |      1       |       2       |       3       |
 |              |               |               |
 |--------------+---------------+---------------|
 |              |               |               |
 |     1x2      |      2x2      |      3x2      |
 |      4       |       5       |       6       |
 |              |               |               |
 |--------------+---------------+---------------|
 |              |               |               |
 |     1x3      |      2x3      |      3x3      |
 |      7       |       8       |       9       |
 |              |               |               |
 |----------------------------------------------|

🖱️ MOUSE COMMANDS 🖱️

  • warp — this command moves the mouse pointer to the center of the keynav window. teleportation but make it desktop. 🌀
  • click [button] — this command will send a mouse click. it does not move the mouse, so the click will go wherever the mouse is positioned. the button values are this: 1 = left, 2 = middle, 3 = right, 4 = wheel up, 5 = wheel down.
  • doubleclick [button] — double clicks, but otherwise is the same as click. same button values, twice the drama.
  • drag button [modifier-keys] — starts or ends dragging, depending on state (dragging or not). the button values are the same as for click. the modifier-keys value allows you to specify any keys to 'hold' while dragging, such as alt or shift.
ngl, dragging sometimes doesn't work. the author is trying to make it more reliable. file a bug if you are interested in this feature working :) 🐛

🧃 MISC COMMANDS 🧃

  • record [file] — record actions for replay later. very similar to vim's 'q' command. the first key you press after starting a new recording becomes the active key for that recording. you cannot record to keys that are already bound to other commands, but you can overwrite existing recordings. if you want to persist recordings across keynav processes (like system or keynav restarts, etc) you will want to specify a file. the author uses ~/.keynav_macros but any path will do.

for example, this config: 'q record'. pressing 'q' then 'l' will start recording to the 'l' key assuming it's not already bound. then, to stop recording, press 'q' again (the record key as configured). after that, to replay that recording, simply press playback and then 'l' while the keynav window is active. muscle memory but you made it yourself. 🎬

  • playback — replay a previously recorded sequence of keys. after invoking the command, keynav will wait for the key of a previously recorded session.
  • sh command — run a command with /bin/sh -c <command>. this is slightly outside the scope of keynav, but executing arbitrary commands is very useful when combined with xdotool. for example, the author uses this to activate Google Chrome and focus the URL bar:
g sh "xdotool search --name -- '- Google Chrome' windowactivate key --window 0 --clearmodifiers ctrl+l",end
  • loadconfig path — load an additional config file. paths like '~/foo/bar' are valid and the '~' will be replaced with your home directory (value of $HOME in environment). 🏡
  • start — start keynav. any keys with this binding will operate as global bindings to activate keynav. the moment of arrival. ✨
  • end — end keynav. this hides the keynav window and otherwise makes keynav inactive until the next start command. nap time. 😴
  • history-back — go backwards in command history. all activity is tracked in history, so if you want to undo a movement, etc, simply use this command. undo but for your vibes. ↩️
  • quit — exit keynav. the process will shutdown. bye bestie 👋
  • restart — restart keynav. useful for reloading the configuration. SIGHUP and SIGUSR1 also invoke this command. glow-up via reload. 🔄

📏 CUT AND MOVE VALUES 📏

the values for cuts and moves have two kinds of values. two flavors, one icon. 🍦

  • values in the range [0,1] are taken to mean a percentage of the window's width or height.
  • values > 1 are taken literally as pixel units.

some examples:

  • cut-up 0.75 — this will cut and keep 75% of the window's height. that is, if the window is 1000 pixels tall, then after this cut it will be 750 pixels tall. math ate. 🔥
  • move-left 1 — the '1' here means 100% of the width. this will move the window to the left by the full width of the window.
  • move-down 100 — the '100' here means 100 pixels. this will move the window down by 100 pixels.

🖥️ SCREEN EDGES 🖥️

when moving the keynav window around, the window will not go outside of the screen boundaries. boundaries, queen. 💅

one exception is for multiple displays: a movement outside of the current screen can move the keynav window to the next screen if keynav thinks it's the right thing to do. she has judgment.

if a move would take you beyond the screen borders, then the window will stop moving at the edge. that's it, that's the wall. 🧱

🌸 DEFAULT CONFIGURATION 🌸

okay bestie, here's the whole entire ✨factory settings✨ vibe — this is literally what keynav runs with if you never touch a keynavrc in your life. every single line, no cap:

clear
ctrl+semicolon start
Escape end
ctrl+bracketleft end
q record ~/.keynav_macros
shift+at playback
a history-back
h cut-left
j cut-down
k cut-up
l cut-right
shift+h move-left
shift+j move-down
shift+k move-up
shift+l move-right
space warp,click 1,end
Return warp,click 1,end
semicolon warp,end
w warp
t windowzoom
c cursorzoom 300 300
e end
1 click 1
2 click 2
3 click 3
ctrl+h cut-left
ctrl+j cut-down
ctrl+k cut-up
ctrl+l cut-right
y cut-left,cut-up
u cut-right,cut-up
b cut-left,cut-down
n cut-right,cut-down
shift+y move-left,move-up
shift+u move-right,move-up
shift+b move-left,move-down
shift+n move-right,move-down
ctrl+y cut-left,cut-up
ctrl+u cut-right,cut-up
ctrl+b cut-left,cut-down
ctrl+n cut-right,cut-down

look at all those shortcuts living their best lives 😌 the arrow-key-shaped h j k l family, the diagonal besties on y u b n, and their lil ctrl-twins doing the exact same moves. iconic behavior, truly.

🦋 EXAMPLES 🦋

want a lil taste of what customizing looks like? here:

# Make 'v' paste things:
v sh "xdotool key shift+Insert",end

so you're binding v, telling keynav to shell out with sh and run xdotool key shift+Insert, and then end so keynav chills out afterwards. chef's kiss 💅

also!! the author's own keynavrc is out here as a whole example if you wanna snoop, right here:

http://semicomplete.googlecode.com/svn/keynav/examples/keynavrc.jordan

go look, it's giving study notes from the main character himself 🙈

💜 SEE ALSO 💜

yeah xdotool is the sibling energy here — keynav clicks and warps, xdotool does the key-pressing, they're a whole duo 🫶

🎀 CONTACT 🎀

got questions? comments? a whole essay of feelings? send them to keynav-users@googlegroups.com. 💌

bugs and feature requests go right here:

http://code.google.com/p/semicomplete/issues/list

and honestly, if email is more your vibe, you can just file bugs by emailing the list too. whatever works for you :)

no gatekeeping, no weird forms, just vibes and a mailing list 🧚

👑 AUTHOR 👑

keynav was written by Jordan Sissel.

and that's the whole page bestie!! 💖 this was KEYNAV(1), dated 2025-06-01 — go forth, cut some rectangles, warp your cursor, and make your mouse genuinely jealous. periodt. 💅✨

📦 where this page comes from