Using Neru
A tour of every mode, from moving the cursor to clicking, dragging and scrolling. It takes about ten minutes. Neru should be running with its permissions granted. See Getting started.
The hotkeys below are the macOS and Windows
defaults. On Linux, bind them
first as in Getting started, or
run the command shown next to each one, such as neru hints.
Every mode works the same way
Section titled “Every mode works the same way”- Press a hotkey. An overlay appears, and Neru reads every key until you leave.
- Type keys to pick a point. The cursor moves there.
- Act on it.
Shift+Lleft-clicks,Shift+Rright-clicks,Shift+Mmiddle-clicks. - Press
Escapeto leave the mode.
In hints, the grids and scroll, the arrow keys nudge the cursor a few pixels, so you can correct a near miss before you click.
Primary+Shift+Space, or neru hints.
- Press the hotkey. Every clickable element in the focused window gets a
short label such as
asorf. A disabled element, such as a greyed-out button, gets none, since clicking it does nothing. - Type a label. The cursor moves to that element, and fresh labels appear so you can pick again.
- Press
Shift+Lto click it.
If you mistype, press Backspace. To find an element by its text instead of
its label, press / and type. The
[hints] default hotkeys list
every key hints mode answers.
Hints read the app’s accessibility tree, so they suit native apps, browsers
and Electron. If an app shows few or no hints, use a grid mode, or try another
hint strategy. neru roles --explain
shows which native roles your clickable_roles select here, and
Troubleshooting
covers the common causes. A tool that knows where the controls are can also
supply the targets.
Click on select. Most people want hints to click as soon as the label is
typed, like Vimium. Bind hints --action left_click, as in
Recipes. To hand the picked
point to a script instead, add --on-exit steps, which read it from NERU_X
and NERU_Y. See Scripting.
Recursive grid
Section titled “Recursive grid”Primary+Shift+C, or neru recursive_grid.
- Press the hotkey. The screen splits into a grid with one key per cell, by
default 3x3 with
r t y,f g h,v b n. Size and keys are under[recursive_grid]. - Press the key for the cell that holds your target. The cursor jumps to its center and that cell splits again.
- Repeat until the cursor is on the target, usually two or three presses.
- Press
Shift+Lto click.
Backspace goes back one level, and Space starts over. Recursive grid needs
nothing from the app, so it works in canvases, games and remote desktops.
Bisect
Section titled “Bisect”Primary+Shift+B, or neru bisect.
Bisect halves the screen instead of splitting it into cells, so there are no labels to read.
- Press the hotkey. Neru splits the screen into four quadrants.
- Press
h,j,korlto keep the left, bottom, top or right half, ory,u,bornto keep a quadrant. The cursor moves to the center of what you kept. These are the[bisect]default hotkeys. - Repeat until the cursor is on the target, then press
Shift+L.
Backspace undoes the last cut, and Space starts over.
Primary+Shift+G, or neru grid.
- Press the hotkey. The screen fills with labeled cells.
- Type a cell’s label. A 3x3 subgrid opens inside it.
- Type a subgrid key. The cursor moves there.
- Press
Shift+Lto click.
Grid suits coarse jumps across large monitors. Space starts over.
neru grid --no-subgrid skips step 3. The label alone selects the cell’s
center, so neru grid --no-subgrid --action move_mouse saves a key on every
jump. Bind it to a second hotkey to keep the subgrid on the first.
Scroll
Section titled “Scroll”Primary+Shift+S, or neru scroll.
- Move the cursor over the pane you want to scroll, with any mode.
- Press the hotkey.
- Press
jandkto scroll down and up, thenEscapewhen you are done.
The [scroll] default hotkeys
list the keys for paging, jumping to the top and scrolling sideways.
neru vim.
Vim mode has no default hotkey, so bind one:
[hotkeys]"Primary+Shift+V" = "vim"- Press the hotkey. Neru reads the text in the focused window and puts a cursor on the character nearest the mouse pointer. A status bar shows the mode and the command being typed.
- Move with vim’s keys, such as
w,b,j,k,f,/and counts. To jump anywhere, presss, type a few characters of the target, then the label that appears on it. The jump and search find text in another script by its romanization, soshenzhenfinds 深圳 andborisfinds Борис. This works once Neru has read that script, and on Linux that needs the script’s tesseract data installed. The jump also finds the initials of words, sosasjumps to “Save As”. Labels appear once Neru has finished reading the screen, and until then every key adds to the text. - Act on it.
Returnclicks the character under the cursor,yand a motion copy the text as read, andi,cordedit the app’s text in place. - Press
Escapeto leave. With a command half typed, the firstEscapecancels it.
Vim mode keeps every key for vim, so it does not bind the shared keys in
the next section, such as Shift+L. gc, gr and gm click, and
:leftdown and :leftup around a motion drag. On macOS it needs the Screen
Recording permission, see Getting started.
neru vim lists every key and what an edit
does to the app, and [vim.keymaps]
remaps them.
More than a left click
Section titled “More than a left click”These work in every mode except monitor select, which only picks a display, and vim, which has its own keys for them.
Double and triple click. Bind a chain, such as
"Ctrl+Enter" = "action left_click,left_click". See
Recipes.
Drag. Move to the start point, press Shift+I to hold the left button,
move to the end point with the same mode or the arrow keys, then press
Shift+U to release. Leaving the mode releases any held button. Right and
middle drag are in Recipes.
Sticky modifiers. Tap Cmd, Ctrl, Alt or Shift on its own inside a
mode. It stays held, shown next to the cursor, for every following click and
scroll, so Cmd then Shift+L is a Cmd-click. Tap it again to release it. See
[sticky_modifiers].
Glide. With [held_repeat] enabled = true, holding an arrow key glides
the cursor instead of stepping, and accel_enabled = true speeds it
up the longer you hold. See
[held_repeat].
Several monitors
Section titled “Several monitors”Hints and grids draw on the monitor under the cursor. To jump to another monitor, enable monitor select and bind it:
[monitor_select]enabled = true
[hotkeys]"Primary+Shift+M" = "monitor_select"Each display shows a number. Type one and the cursor moves there.
Next steps
Section titled “Next steps”- Configuring Neru: where the config lives and how to apply changes.
- Recipes: ready-made bindings, such as click on select and restoring the cursor after a click.
- How bindings work: what a binding can run, and which one wins inside a mode.