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 query hints for every element hints would label in the focused window, with its role and text, without drawing anything. Run it first for any "hints show nothing in app X" report. From a terminal it reports the terminal, so run it from a hotkey or as sleep 3; neru query hints. Versions before it have neru hints --debug, which prints a sample.
• 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:

Doc	Before the move	What it covers
reference/cli.md	CLI.md	every command and flag
guide/scripting.md	CLI.md	driving Neru from scripts and other hotkey tools
reference/ipc.md	CLI.md	the IPC protocol
reference/configuration.md	CONFIGURATION.md	every key with its default and platform column
concepts/bindings.md	CONFIGURATION.md	what a binding can run, and which binding answers a key
concepts/glossary.md	not in older releases, skip it	the words the docs use
guide/getting-started.md	CONFIGURATION.md	first launch, permissions, first hotkey
guide/using-neru.md	CONFIGURATION.md	how each mode is used, clicks, drag, sticky modifiers
guide/configuring.md	CONFIGURATION.md	config file location, layering, reloading, config set
guide/recipes.md	TIPS_TRICKS.md	worked recipes such as Vimium-style click on select, drag with any button, cycling modes on one key, and driving Neru from skhd
guide/troubleshooting.md	TROUBLESHOOTING.md	when something does not work
guide/installation.md	INSTALLATION.md	install methods and login services
reference/platform-support.md	CROSS_PLATFORM.md	what each platform supports
guide/linux.md, guide/linux-desktops.md	LINUX_SETUP.md, LINUX_DESKTOPS.md	Linux permissions and per-compositor notes

What Neru does

Ask	Answer with
Click something on screen by keyboard	neru hints --action left_click, or right_click, middle_click
Click where hints find nothing	neru grid, neru recursive_grid or neru bisect, or neru hints --strategy vision
Filter hints by typing	neru hints --search, or / inside hints
Scroll without a mouse	neru scroll, or neru action scroll_down --steps N
Move the cursor to a spot, display, or grid cell	neru action move_mouse, move_monitor, move_cell
Nudge the cursor and keep it moving while held	neru action move_mouse_relative, glide under [held_repeat]
Drag	left_click --state down, move, left_click --state up
Jump between monitors	neru monitor_select
Type text or press keys	neru action feed
Click without moving the real cursor	save_cursor_pos, then the click, then restore_cursor_pos
Chain steps as one unit	neru run "..." "...", or [macros] in config, see neru-setup-config
Bind a key to any of the above	[hotkeys] in config, see neru-setup-config
Change hint letters, colours, grid size	neru config set <key> <value>, see neru-setup-config
Make one app behave differently	[[hints.app_configs]] by bundle id, see neru-setup-config
Hide overlays while screen sharing	neru toggle-screen-share
Run Neru at login	neru services install, see neru-setup-config
Pause Neru without quitting	neru stop, then neru start

Things a user often does not know:

• Hints have four 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, and segment finds controls and words from pixels 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 query hints 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.

Routing

• Config, hotkeys, macros, modes, per-app overrides, or service work goes to neru-setup-config.
• Building a tool on Neru, such as a status bar, a launcher, or a program that reads its state or drives it, goes to neru-build-integration.
• A question with a one-command answer gets the command and the help page that documents it.
• When something does not work, in this order: neru status, neru doctor, then neru query hints for a hints report or neru config validate for a hotkey report, then the Troubleshooting doc as above, before guessing at a cause. Its Permissions and Hotkeys Not Working sections cover most reports. On macOS, a hotkey that never fires after an update is usually a stale Accessibility grant. Remove Neru from the list and add it again.
• A bug or a missing feature goes to a GitHub issue on y3owk1n/neru. Blank issues are disabled, so use the issue forms, and include neru --version and neru doctor output. Questions and config help belong in Discussions.

Do not answer flags or key names from memory. Run --help or read the man page first.