neru-ask
Answer a Neru user's question about what Neru does, which command, flag, or config key does a thing, why something does not work, or what to try next, from the help, man pages, and docs of their insta
SKILL.md.agents/skills/neru-ask/SKILL.md
GitHubAnswering 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, thenneru <command> --help. The help lists the flags and accepted values of the installed version.man neruon macOS and Linux, and one page per subcommand such asman neru-hints,man neru-config-set, andman neru-action-left_click.apropos nerulists them. Windows has noman, and--helpcarries the same text.neru statusfor whether the daemon runs and which mode is open.neru doctorfor config validity, socket health, permissions, and which capabilities this platform has. It runs without the daemon.neru query hintsfor 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 assleep 3; neru query hints. Versions before it haveneru hints --debug, which prints a sample.neru config dumpfor the config in force, defaults filled in.neru roles --explainfor the clickable roles and how each resolves here.neru docs cliandneru docs configopen 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.
axtreereads the accessibility tree and is the default.visionrecognises text on a screen capture, and on macOS rectangles too.contourfinds edges on every platform, andsegmentfinds controls and words from pixels on every platform. An app with a poor tree, such as an Electron app or a game, gets--strategy visionfor 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 hintsshows what was collected,neru roles --explainshows what the platform can name, andneru hints --roleoverrides 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_supportinneru doctor. It is not an error. - Runtime toggles do not persist.
toggle-scroll-invert,toggle-cursor-follow-selection, andtoggle-screen-sharelast 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, andstatusall talk to it.config init,config validate,doctor, androlesrun without it. - There is no log file by default.
logging.disable_file_loggingistrueout of the box. Before telling a user to read the log, have them set it tofalseand restart, then read~/Library/Logs/neru/app.logon macOS,~/.local/state/neru/log/app.logon Linux, or%LOCALAPPDATA%\neru\log\app.logon 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, thenneru query hintsfor a hints report orneru config validatefor 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 includeneru --versionandneru doctoroutput. Questions and config help belong in Discussions.
Do not answer flags or key names from memory. Run --help or read the man
page first.