Neru Ask

Answering questions about Neru

Neru is a keyboard-driven mouse replacement. A daemon watches global hotkeys and draws overlays, and a CLI sends it commands over a socket. Modes take the keyboard until a target is picked: hints label clickable elements, grid and recursive grid divide the screen, scroll moves content, monitor select jumps between displays. Actions click, scroll, and move the cursor without a mode. Every answer should come from the installed version, since commands, flags, and keys change between releases.

What every install has

Check these before anything remote. The install script, Homebrew, Nix, and a source build all ship them.

• neru --help, then neru <command> --help. The help lists the flags and accepted values of the installed version.
• man neru on macOS and Linux, and one page per subcommand such as man neru-hints, man neru-config-set, and man neru-action-left_click. apropos neru lists them. Windows has no man, and --help carries the same text.
• neru status for whether the daemon runs and which mode is open.
• neru doctor for config validity, socket health, permissions, and which capabilities this platform has. It runs without the daemon.
• neru hints --debug for the elements hints would label in the focused window, as a count and a sample, without drawing anything. Run it first for any "hints show nothing in app X" report.
• neru config dump for the config in force, defaults filled in.
• neru roles --explain for the clickable roles and how each resolves here.
• neru docs cli and neru docs config open the two references in a browser at the installed version.

For anything the help does not cover, fetch the doc at the installed version:

tag=$(neru --version | sed -n '1s/^Neru version //p' | cut -d- -f1)
case $tag in v*.*.*) ;; *) tag=main ;; esac
base="https://raw.githubusercontent.com/y3owk1n/neru/$tag/docs"
curl -fsSL "$base/reference/cli.md" || curl -fsSL "$base/CLI.md"

A release build prints its tag. A dev build prints v1.2.3-14-gabcdef, which the cut maps to the release it was built from. On Windows, where sed and cut are usually absent, the same fetch in PowerShell:

$tag = (((neru --version)[0] -replace '^Neru version ', '') -split '-')[0]
if ($tag -notmatch '^v\d+\.\d+\.\d+$') { $tag = 'main' }
$base = "https://raw.githubusercontent.com/y3owk1n/neru/$tag/docs"
try { Invoke-RestMethod "$base/reference/cli.md" } catch { Invoke-RestMethod "$base/CLI.md" }

Each doc, with the name it had in releases before the docs moved. When the new path returns 404, the installed release predates the move, so fetch the old name from the same docs/ URL:

What Neru does

Things a user often does not know:

• Hints have three strategies. axtree reads the accessibility tree and is the default. vision recognises text on a screen capture, and on macOS rectangles too. contour finds edges on every platform. An app with a poor tree, such as an Electron app or a game, gets --strategy vision for one call or a per-app strategy in config.
• Grid modes need no accessibility tree. When hints show nothing in an app, grid and recursive grid still work, because they divide the screen rather than read elements.
• Hints only label roles in hints.clickable_roles. A missing hint is usually a role outside that list. neru hints --debug shows what was collected, neru roles --explain shows what the platform can name, and neru hints --role overrides the list for one call.
• Inside a mode the keys are bindable too. Each mode has its own [<mode>.hotkeys] table, so Shift+L for a left click inside hints, Tab to cycle, and the arrow keys to nudge are defaults, not fixed.
• Linux ships no default global hotkeys. The modes exist but nothing is bound until [hotkeys] or the compositor binds them. That is by design.
• One config works on every platform. A key, flag, or action the current platform cannot act on loads with a warning, listed under platform_support in neru doctor. It is not an error.
• Runtime toggles do not persist. toggle-scroll-invert, toggle-cursor-follow-selection, and toggle-screen-share last until the daemon restarts. The lasting form is the config key.
• The CLI needs the daemon for most things. Modes, actions, config set, config dump, and status all talk to it. config init, config validate, doctor, and roles run without it.
• There is no log file by default. logging.disable_file_logging is true out of the box. Before telling a user to read the log, have them set it to false and restart, then read ~/Library/Logs/neru/app.log on macOS, ~/.local/state/neru/log/app.log on Linux, or %LOCALAPPDATA%\neru\log\app.log on Windows.