CLI reference
Every neru command and flag. The same content ships as man pages
(man neru). To drive Neru from scripts, see Scripting.
neru launch starts the daemon. Every other command sends one request to it
and prints the reply, except doctor, roles, describe, schema,
agent-guide, services, docs, config init and config validate, which
run without a daemon.
Synopses use <value> for a required value, [--flag] for an optional flag,
a|b for a choice, and [<key>...] for a repeatable argument. Every command
also takes -h/--help. A command that does nothing on your platform says so
and exits non-zero, and
Platform support per word
lists the flags and actions this applies to.
Every command exits 0 on success and 1 on any failure. When the daemon
refuses a request, the error line on stderr ends with its
response code, as in (code: ERR_NOT_RUNNING).
Scripts read that code, since the exit status is the same for every failure.
Global flags
Section titled “Global flags”| Flag | Shorthand | Type | Default | Description |
|---|---|---|---|---|
--config | -c | string | "" | Config file path. Overrides the default search paths. See Config file location. |
--timeout | int | 10 | IPC timeout in seconds. |
neru --version, or neru -v, prints the version, git commit and build date.
It works on neru itself, not after a subcommand.
Daemon lifecycle
Section titled “Daemon lifecycle”neru launch
Section titled “neru launch”neru launch [-c <path>] [--timeout <seconds>]Start the daemon that owns the event tap, overlays and IPC server. Takes only
the global flags. With a daemon already running, it prints
Neru is already running and exits 0.
neru start
Section titled “neru start”neru startResume mode switching and overlay rendering after neru stop.
Errors: ERR_ALREADY_RUNNING when Neru is not stopped.
neru stop
Section titled “neru stop”neru stopDisable mode switching and overlay rendering, and exit the active mode. The
daemon keeps running and keeps its socket open. Until neru start, the mode
commands, action, run and macro fail with ERR_NOT_RUNNING. The
IPC Commands table lists what still answers.
Errors: ERR_NOT_RUNNING when Neru is already stopped.
neru idle
Section titled “neru idle”neru idleExit the active mode. Does nothing when no mode is active. Takes no flags or arguments, and refuses anything written after it.
neru status
Section titled “neru status”neru status [--json]Print the daemon state and the current mode.
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | Print the state as one JSON object. |
The human form prints Status (running, or stopped after neru stop) and
Mode (idle, hints, grid, recursive_grid, bisect, scroll,
monitor_select, vim, or the name of the open declared mode).
It then prints Config, Platform, the adapter profile, and the runtime
toggles as yes or no. Cursor follows selection appears only while it has
a value. With --json, the object goes to stdout alone, and errors go to
stderr with a non-zero exit status.
| Key | Type | Description |
|---|---|---|
enabled | bool | false after neru stop, true after neru start. |
mode | string | The active mode, same values as Mode. |
config | string | Path of the config file in use. |
hints_enabled, grid_enabled, recursive_grid_enabled, bisect_enabled | bool | Whether each mode is enabled in the config. |
scroll_inverted | bool | Set by toggle-scroll-invert. |
hidden_for_screen_share | bool | Set by toggle-screen-share. true means hidden. Always false on Linux, where nothing hides the overlay. |
cursor_follow_selection | bool or null | Set by toggle-cursor-follow-selection. null unless hints, grid, recursive_grid or bisect is active, so test for null before reading it as a boolean. |
saved_cursor_slots | object | The occupied cursor slots, each {"x": …, "y": …}. Empty when none are saved. |
sticky_modifiers | string | The sticky modifiers held, such as cmd,shift. Empty when none is. |
capabilities | object | Per-subsystem support on this platform, as neru doctor reports it. |
profile | object | Which adapter serves each subsystem, and whether it needs CGO. |
Every key except capabilities and profile is stable. Those two gain
entries as subsystems are added, so read only the keys you need.
neru watch
Section titled “neru watch”neru watch [--event <name>[,<name>...]]Print the status, then one JSON object per line for each event the daemon
publishes, as it happens. The events are the ones [hooks]
runs on, named without the on_ prefix. The hook on_mode_enter runs on the
event mode_enter.
| Flag | Type | Default | Description |
|---|---|---|---|
--event | string | none | Print only these events, comma-separated, such as mode_enter,mode_exit. Repeat to add more. Snapshots always print. An unknown name fails with ERR_INVALID_INPUT. |
{"seq":0,"event":"snapshot","status":{"enabled":true,"mode":"idle"}}{"seq":1,"event":"mode_enter","mode":"hints"}{"seq":2,"event":"mode_exit","mode":"hints","reason":"completed"}{"seq":3,"event":"config_reload","ok":false}The snapshot line comes first, with status holding the object
neru status --json prints (shortened above). Every line after
it is an event, except when the reader falls behind. Then the daemon replaces the
events it missed with a fresh snapshot carrying a dropped count, so take each
snapshot as the whole state and each event as a change to it.
| Key | Present on | Value |
|---|---|---|
seq | every line | Rises by one with each event. On a snapshot, the seq of the last event it includes. With --event, it skips the events left out. |
event | every line | snapshot, or the event, such as mode_enter |
status | snapshot | The neru status --json object |
mode | mode_enter, mode_exit, select | The mode, named as neru status names it |
reason | mode_exit | completed, switched or canceled, as NERU_REASON has them. A mode_exit with switched is always followed by the next mode’s mode_enter. A switch whose next mode fails to open, such as hints finding nothing to label, reports canceled |
action | select, and mode_exit when completed | The action the selection ran, such as left_click, or snap for a snap. Absent when it ran none, such as for a binding with no --action |
bundle_id | app_focus | The application, as bundle_id names it |
ok | config_reload | true or false |
on | scroll_invert, screen_share_hide | The state switched to, as scroll_inverted and hidden_for_screen_share report it |
slot | cursor_save, cursor_restore | The cursor slot |
x, y | cursor_save, select | The position saved, or the point selected or snapped to |
modifiers | sticky_modifiers | The set held now, as sticky_modifiers reports it |
monitor | monitor_move | The display moved to, as move_monitor --name takes it |
dropped | a snapshot after missed events | How many events this snapshot replaces. With --event, only the events named count, and the rest can never fill the reader’s buffer. |
The daemon disconnects a reader once a line has
waited 5 seconds to send. At most 16 watches can be open at once, and the next
one fails with ERR_BUSY.
The command runs while Neru is stopped too, and exits 0 when the daemon exits.
--timeout bounds connecting only, never the stream.
Errors: ERR_INVALID_INPUT for an unknown event name, ERR_BUSY when 16
watches are open. Every key is stable.
neru query
Section titled “neru query”neru query displays [--json]neru query cursor [--json]neru query window [--json]neru query app [--json]neru query hints [--role ...] [--text ...] [--strategy ...] [--capture-scope ...] [--label-direction ...] [--split-word] [--json]Print what the daemon sees right now. Positions and sizes use the coordinates
move_mouse takes, with a global top-left origin
and Y growing down. Queries answer while Neru is stopped, as neru status
does, except query hints.
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | Print the answer as one JSON object on stdout. Errors still go to stderr with a non-zero exit status. |
query hints also takes six hints flags, listed with it below.
Errors: ERR_NOT_SUPPORTED when the platform cannot answer the query, and
ERR_ACTION_FAILED when it tried and failed. Every key is stable.
neru query displays lists every connected display, in the order the
platform enumerates them.
{"displays":[{"name":"Built-in Retina Display","x":0,"y":0,"width":1512,"height":982,"scale":1}]}| Key | Type | Description |
|---|---|---|
name | string | The name move_monitor --name takes. Two identical monitors can share one. |
x, y, width, height | int | The display’s bounds. |
scale | number | Physical pixels per apparent unit. The display’s DPI scale on Windows and X11, and 1 on macOS and Wayland, whose bounds are already logical. |
neru query cursor prints the cursor position and the display holding it.
Where Neru caches the position, as on Wayland, it refreshes it first, and
fails with ERR_ACTION_FAILED rather than report a position it could not
refresh.
{"x":812,"y":440,"display":"Built-in Retina Display","display_index":0}| Key | Type | Description |
|---|---|---|
x, y | int | The cursor position. |
display | string or null | The display’s name, as query displays lists it. null when no display holds the cursor. |
display_index | int or null | The display’s position in the query displays list, which tells apart two displays that share a name. |
neru query window prints the focused window’s bounds. When no window has
focus, such as when the desktop does, it prints No window has focus, and
with --json it prints null. A Wayland compositor that exposes no window
geometry fails it with ERR_NOT_SUPPORTED. GNOME needs the
Neru GNOME Shell extension.
{"x":0,"y":25,"width":1440,"height":875}| Key | Type | Description |
|---|---|---|
x, y, width, height | int | The window’s bounds. |
neru query app prints the focused application. Run from a terminal, it
reports the terminal, so give yourself time to switch:
sleep 3; neru query app{"bundle_id":"com.apple.Safari"}| Key | Type | Description |
|---|---|---|
bundle_id | string | The application, read from the same source per-app config matches against. It is the exact string to write in [[app_configs]]. |
GNOME needs the Neru GNOME Shell extension here too.
neru query hints lists the elements hints mode would label in the focused
window, without drawing the overlay or entering the mode. Like query app, it
reports the terminal when run from one.
It takes the hints flags that decide which elements it collects, and
--label-direction, which decides their labels. Each works as in the
mode flag reference.
| Flag | Type | Default | Description |
|---|---|---|---|
--role | string, repeatable | none | Only these roles. |
--text | string, repeatable | none | Only elements whose text contains one of these. |
--strategy | string | hints.strategy | How to find elements. |
--capture-scope | string | hints.capture_scope | Region vision, contour and segment scan. |
--split-word | bool | false | One element per word of detected text. Needs vision. |
--label-direction | string | hints.label_direction | Label order. |
Unlike the other queries, it does not answer while Neru is stopped, because
the vision, contour and segment strategies capture the screen. It fails with
ERR_NOT_RUNNING then. When one of those scans fails, the query fails with
its error, where hints mode would open on what else it found.
{"hints":[{"label":"A","role":"ax:AXButton","title":"","description":"Back","value":"","source":"axtree","identifier":"back-button","focused":false,"x":100,"y":38,"width":44,"height":52}]}| Key | Type | Description |
|---|---|---|
label | string | The label neru hints with the same flags would draw on the element now. |
role | string | The native role, spelled as --role takes it, such as ax:AXButton. |
title, description, value | string | The element’s text. --text matches any of the three. Empty when the element has none. |
source | string | What found the element: axtree, vision, contour or segment, as --strategy names them. Actions on an axtree element can use its accessibility handle. On the others they act at its coordinates. |
identifier | string | The ID the app’s developer gave the element, such as an AXIdentifier, UI Automation AutomationId or AT-SPI AccessibleId. It does not change with the element’s text or language, so it is the steadiest way to find one element. Empty when the app set none. |
focused | bool | Whether the element has keyboard focus. |
x, y, width, height | int | The element’s bounds. |
identifier and focused come from the accessibility tree, so they mean
something only when source is axtree. An element found any other way
reports "" and false.
Neru assigns labels afresh on every scan, after the flags filter the
elements. A label stays valid only while the screen does not change, and only
for neru hints given the same --role, --text, --strategy,
--capture-scope, --split-word and --label-direction. To select an
element by its label:
- Run
neru query hintswith the flags you need, and read the label. - Start hints mode with exactly the same flags, plus
--action. - Type the label into the mode with
neru action feed --mode, one key per character, before the screen changes.
label=$(neru query hints --text Save --json | jq -r '.hints[0].label')neru hints --text Save --action left_clickneru action feed --mode $(echo "$label" | fold -w1)neru doctor
Section titled “neru doctor”neru doctor [--json]Report config validity, socket health, platform capabilities from the capability matrix, and component state.
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | Print every check as one JSON object. |
- With the daemon running, the
Overlay backendline names the renderer in use. On Windows it tells DirectComposition + Direct2D from the GDI fallback and says why the fallback was taken. - The
platform_supportrow lists the options, actions and mode flags your config writes that do nothing on this platform, with the reason for each. These never fail the check. The full set is in Platform support per word. - The check fails when the config fails to load or selects no role that
applies here, when the daemon reports an unhealthy component, or when no
daemon is running. A daemon paused by
neru stopstill answers and does not fail it. On Windows a daemon that is not running does not fail it, and the command prints its client-side checks instead.
With --json, the object goes to stdout alone, and the exit status is the same
as without it. The object leaves out the checks Windows prints while no daemon
is running.
| Key | Type | Description |
|---|---|---|
healthy | bool | false exactly when the command exits non-zero. |
config | object | path is the config file checked, empty for the built-in defaults. error says why it failed to load, and is empty when it loaded. |
clickable_roles | object | How hints.clickable_roles resolves here. entries counts the entries written, native the native roles they select, and ignored the entries for other platforms. usable is false when no role applies. |
platform_support | object or null | inert lists {"written": …, "note": …} for each setting that does nothing here. null when the config failed to load, or when Neru declares no platform support for this OS. |
ipc_endpoint | object | path is where the daemon listens, empty when Neru cannot determine it for this user. reachable is whether the daemon answers there. |
daemon | object or null | The health reply’s data. null when the daemon does not answer. |
Every key is stable except the contents of daemon, which follow the health
reply.
Navigation modes
Section titled “Navigation modes”Mode flag reference
Section titled “Mode flag reference”Flags work the same typed after neru, in a
hotkey binding, or over the
IPC socket. A mode refuses a flag not listed for it. A repeated flag
replaces its earlier value unless its entry says it can be repeated.
--action may be positional: hints left_click.
--actiontakes the mouse-button action names ormove_mouse, and in hints alsocopy_text.--on-exitsteps form one action sequence.hints --action move_mouse --on-exit scrollopens scroll mode on the hint you pick.--roletakes theneru rolesvocabulary.--label-directionis explained in Choosing a label direction.- A flag left out takes its config value:
--strategyfromhints.strategy,--label-directionfromhints.label_direction.--cursor-selection-modedefaults tofollow.
Cycling lists. A --strategy or --capture-scope list follows these rules:
- The value in use may come from the config.
- The list wraps, and falls back to its first entry if it does not name the value in use.
- With
--toggle, a press while the mode is on the last entry closes it instead of wrapping.hints --strategy axtree,contour --toggleopens onaxtree, steps tocontour, then closes. - Each value may appear once.
- Only one flag per command may take a list.
--split-wordrefuses a--strategylist.
--action
Section titled “--action”Shorthand -a. Takes a value. Modes: hints · grid · recursive_grid.
Action to run on the selection: left_click, right_click, middle_click, left_mouse_down, left_mouse_up, right_mouse_down, right_mouse_up, middle_mouse_down, middle_mouse_up, left_mouse_toggle, right_mouse_toggle, middle_mouse_toggle, move_mouse. move_mouse only leaves the cursor there. Chain with commas, as in left_click,left_click. In hints, copy_text copies the hint’s text instead, and takes no chain.
--modifier
Section titled “--modifier”Takes a value. Modes: hints · grid · recursive_grid.
Modifiers to hold during the action, comma-separated: cmd, super, meta, shift, alt, option, ctrl. Needs —action.
--on-exit
Section titled “--on-exit”Takes a value, and can be repeated. Modes: hints · grid · recursive_grid.
Step to run after the action, written as in a hotkey binding. Repeat for more steps. Needs —action and refuses —repeat. Does not run if the mode is canceled. Exec steps see the selection as NERU_X, NERU_Y, NERU_MODE and NERU_ACTION.
--repeat
Section titled “--repeat”Shorthand -r. Takes no value. Modes: hints · grid · recursive_grid.
Reopen the mode after the action runs. Needs —action.
--toggle
Section titled “--toggle”Shorthand -t. Takes no value. Modes: hints · grid · recursive_grid · bisect · scroll · monitor_select · mode · vim.
Open the mode, or leave it if it is already open.
--search
Section titled “--search”Shorthand -s. Takes no value. Modes: hints.
Open with the hint search field showing.
--hide-on-empty-search
Section titled “--hide-on-empty-search”Takes no value. Modes: hints.
Hide every hint until the search has text. Needs —search.
--confirm-on-label
Section titled “--confirm-on-label”Takes no value. Modes: hints.
Confirm the search as soon as a label typed after the search text leaves one match, without Return.
--exit-on-unmatched
Section titled “--exit-on-unmatched”Takes no value. Modes: hints.
Exit when a key matches no hint.
--role
Section titled “--role”Takes a value, and can be repeated. Modes: hints.
Only hint these roles, comma-separated, such as button,link (see ‘neru roles’). Repeat to add more.
--text
Section titled “--text”Takes a value, and can be repeated. Modes: hints.
Only hint elements whose text contains one of these, comma-separated and case-insensitive. Repeat to add more.
--strategy
Section titled “--strategy”Takes a value. Modes: hints.
How hints find elements: axtree (accessibility tree), vision (OCR), contour (shape detection) or segment (controls and labels from pixels). A comma-separated list cycles, moving to the next value each time the command runs while the mode is open, as in —strategy=axtree,vision. With —toggle, running the command on the last value leaves the mode instead of wrapping.
--capture-scope
Section titled “--capture-scope”Takes a value. Modes: hints · grid · recursive_grid · bisect · vim.
Region to work in: window (the focused window) or screen (the whole screen). A comma-separated list cycles, moving to the next value each time the command runs while the mode is open, as in —capture-scope=window,screen. With —toggle, running the command on the last value leaves the mode instead of wrapping.
--label-direction
Section titled “--label-direction”Takes a value. Modes: hints.
Label order: normal (shorter labels first) or reverse (spread across the alphabet).
--targets
Section titled “--targets”Takes a value. Modes: hints.
Label these targets instead of scanning, as JSON in the shape ‘neru query hints —json’ prints. Refuses the flags that decide what a scan collects, and —repeat.
--split-word
Section titled “--split-word”Takes no value. Modes: hints.
Hint each word of detected text separately. Needs the vision strategy.
--no-subgrid
Section titled “--no-subgrid”Takes no value. Modes: grid.
Select a cell’s center as soon as its label is typed, without opening the subgrid.
--zoom-to-depth
Section titled “--zoom-to-depth”Takes a value. Modes: recursive_grid.
Open recursive grid already zoomed to this depth at the cursor.
--cursor-selection-mode
Section titled “--cursor-selection-mode”Takes a value. Modes: hints · grid · recursive_grid · bisect · vim.
Whether the real cursor follows the selection (follow) or stays put (hold).
What a mode command answers
Section titled “What a mode command answers”A mode command succeeds once the daemon accepts the activation, which does not
mean the mode opened. --toggle on the open mode leaves it, and
monitor_select with one display opens nothing, and both still succeed. To
confirm a mode opened, read mode from neru status --json,
or wait for the mode_enter line of neru watch --event mode_enter.
Errors: ERR_MODE_DISABLED when the config sets enabled = false for the
mode, which hints, grid, recursive_grid, bisect, monitor_select and vim can do.
ERR_NOT_RUNNING after neru stop. A flag the mode refuses fails too. The CLI
refuses it before sending, and the daemon answers ERR_INVALID_INPUT.
neru hints
Section titled “neru hints”neru hints [flags]Label the interactive elements of the focused window, and select one by
typing its label. Takes the hints flags in the
mode flag reference. To list what it would label
without the overlay, use neru query hints.
Element discovery uses the full accessibility tree on macOS, an AT-SPI walk
on Linux whose coverage depends on the application, and a cached UI Automation
walk on Windows. The vision strategy is the fallback where the tree is thin.
It works on every platform and needs an OCR language pack on Windows. See
Accessibility and hints.
neru hints --action left_click --role button --text submitSupplying your own targets
Section titled “Supplying your own targets”Where no strategy finds what you need to click, another tool can supply the
targets instead. --targets takes JSON in the shape
neru query hints --json prints, and hints mode labels those
targets in place of a scan. Each target needs x, y, width and height
in the coordinates move_mouse takes. role, title, description and
value are optional, and other keys, such as a query’s label, are ignored.
From the command line, --targets - reads the JSON from stdin.
neru query hints --json | jq '.hints |= map(select(.width > 20))' \ | neru hints --targets - --action left_click- Targets whose center is off the active display are dropped, as scanned elements are.
- A target has no accessibility handle, so every action works at its
coordinates, as it does on what the
visionstrategy finds. --targetsrefuses--role,--text,--strategy,--capture-scope,--split-wordand--repeat. Filter the targets before sending them.- A screen change or a monitor move exits hints mode, since nothing can scan the targets again.
- The request size cap holds several hundred targets.
neru grid
Section titled “neru grid”neru grid [flags]Overlay a grid of labeled cells over the screen, or the focused window with
--capture-scope window. Typing a label opens a 3x3 subgrid in that cell.
move_cell moves the open subgrid to a neighbouring
cell. Takes the grid flags in the mode flag reference.
Size, labels and appearance are under [grid].
neru grid --action left_click --on-exit 'exec notify-send clicked'neru recursive_grid
Section titled “neru recursive_grid”neru recursive_grid [flags]The CLI also accepts neru recursive-grid. Over IPC and in bindings the name
is recursive_grid only.
Subdivide the selected cell on each keypress until you reach the point.
Backspace backtracks one level, and move_cell
moves sideways at the current depth. Takes the recursive_grid flags in the
mode flag reference. Depth and layout are under
[recursive_grid].
--zoom-to-depth drills at the cursor as the mode opens, and stops early at
the minimum cell size or maximum depth.
neru recursive_grid --zoom-to-depth 3 --action left_clickneru bisect
Section titled “neru bisect”neru bisect [flags]Narrow a region by halves or quadrants until the cursor is on the target.
The region starts as the screen, or the focused window with
--capture-scope window, and shows the quadrant keys in its four cells. Each
press keeps one half or quadrant and moves the cursor to its center, or a
pointer stand-in with --cursor-selection-mode hold. Backspace undoes the
last cut, and Space starts over.
Takes the bisect flags in the mode flag reference.
Keys and the default scope are under [bisect],
appearance under [bisect.ui] and [bisect.animation].
neru scroll
Section titled “neru scroll”neru scroll [flags]Scroll at the cursor with vim-style keys. Takes the scroll flags in the
mode flag reference. Step sizes are under
[scroll].
The keys are the [scroll.hotkeys] defaults plus
the keys every mode shares.
neru monitor_select
Section titled “neru monitor_select”neru monitor_select [flags]Show a labeled panel on every other display, and move the cursor to the one
whose label you type. The mode is off by default, so set
monitor_select.enabled = true first, or it fails with ERR_MODE_DISABLED.
It needs more than one display. With one, the command succeeds and opens
nothing. Labels come from
monitor_select.characters, default 123456789, and Escape cancels. Takes
the monitor_select flags in the mode flag reference.
neru vim
Section titled “neru vim”neru vim [flags]Read the text in the focused window, or the whole screen with
--capture-scope screen, and move a cursor over it with vim’s keys. Motions,
counts, text objects, search, registers, macros and . work as in vim. Marks
do not, because every scroll and edit reads the screen again and a mark would
point at other text. For the same reason a read of the screen ends visual
mode, as when j past the last line scrolls the app. Vim mode makes each
edit in the app under the cursor, by clicking the caret into place,
selecting with Shift+Right and typing, then reads the screen again.
Vim mode’s own keys in the table below, such as s, gc and Ctrl+D, are
mappings that [vim.keymaps] can move or
turn off.
| Keys | Does |
|---|---|
i, a, I, A, o, O | Click the app’s caret into place, then type into the app until Escape |
c, d, x, r, J and the rest | Select the text, then erase it or type over it |
p, P | Click into place and type the register’s text, without its □ icons. Vim mode never touches the clipboard |
u, Ctrl+R | The app’s own undo and redo. A count repeats it, up to eight times |
. | Repeat the last change. A change typed into the app repeats with what was typed |
y + motion | Copy the text as read, without touching the app. The copied text flashes and the status bar says how much |
Return, gc, gr, gm | Click the character under the cursor, left with Return or gc, right with gr and middle with gm. A count clicks that many times, up to three, so 2gc or 2 Return double clicks. Vim mode stays open and reads the screen again |
gh, :movemouse | Move the real cursor to the character under the cursor without a click, gliding when smooth_cursor.move_mouse_enabled is on, for a session opened with --cursor-selection-mode hold. Motions after it leave the real cursor where it is |
gs + motion, or Return in visual mode | Drag across the text so the app selects it, then leave. Works on text that cannot be edited |
s + characters + label | Type any number of characters to find, then a match’s label to jump there, or Return for the nearest. Backspace takes back a character. A label is never the character after a match, so typing more of the text never jumps |
]i, [i | Move to the next or the previous icon, with a count to skip |
Ctrl+W + h, j, k, l | Move to the container left, below, above or right, within the block the cursor is in until that block ends |
Ctrl+W + w, W | Move to the next or the previous container |
ic, ac | The container’s text, or with the blank line after it, as yic copies a card. A count takes the block around it, as y2ic copies the column the card is in |
Ctrl+D, Ctrl+U, Ctrl+F, Ctrl+B, Ctrl+E, Ctrl+Y | Scroll the app at once. The overlay stays up while the page moves and the status bar says reading…, and vim reads the screen again once it stops, so a run of scrolls reads only the screen it ends on. A key that acts on the text before that read lands reads the screen first, and vim mode drops it with a notice when that read finds nothing. j and k past the edge scroll too |
zh, zl, zH, zL | Scroll the app left or right eight characters, or the count with one, or half the width read with zH and zL |
zz | Scroll the app until the cursor’s line is in the middle of the region read, or line n of the text read with a count |
Ctrl+L | Read the screen again, keeping registers, macros and the last search |
:s | Replace as in vim. While it is typed, each place it would change is highlighted and the status bar counts them. One command changes at most 64 places, and the changes on one line take one click. Across lines it waits for the screen to show each line changed before it clicks the next, and stops with what it left in the status bar when the screen does not show it within a second |
:q | Leave |
:leftclick, :rightclick, :middleclick + optional number | Click at the cursor that many times, once without one, as :leftclick 2 |
:leftdown, :leftup, :rightdown, :rightup, :middledown, :middleup | Press or release the button at the cursor, so a motion between them drags. Leaving the mode releases a button still held |
Tab, Shift+Tab | On the : line, cycle forward or back through the commands that start with the name typed. The status bar lists them, and after the last the name typed comes back |
Escape | Cancel what is pending, then leave |
Vim mode groups the words of a column, a sidebar or a card into a container,
using the gaps between words, the color behind them and the borders between
them, such as a card’s edge or an input’s outline. It lays each container out
as its own block, so j, k, w and search stay inside the one you are
reading, and it outlines the one the cursor is in. Containers nest, cut apart
at the gaps that run all the way across the screen, so a card sits in a column
and the column in the page. The block around the cursor’s container is
outlined fainter.
Vim mode reads the screen twice. A fast read opens the mode at once, and an
accurate read replaces it when it finishes. The status bar says reading…
until then. The accurate read also finds icons and pictures with no text,
such as an icon-only button, and puts a □ where each one is, so w, j and
s reach it and Return clicks it. A yank leaves the □ out. The box beside
the cursor shows the word under it as read. The counts in one command, such
as both in 99d99j, multiply to at most 9999, and vim mode drops a digit
past that. One command changes at most 64 places and sends the app at most
2000 keys, a Shift+Right for each character it selects and a key for each it
types.
The fast read knows Latin script only. The accurate read finds each line’s
script, so it reads Chinese, Japanese, Korean, Thai, Russian and the other
languages macOS knows. It reads each line in one script. When your macOS
languages include Chinese, Japanese or Korean, it also reads with that
language, so a word of it in an English line is read correctly. Linux and
Windows read fewer scripts, which platform support lists. Until the
accurate read finishes, a line in another script shows as noise. A wide character such as 中
takes two columns, and a character the app moves over in one step, such as
a Thai consonant with its vowel sign, is one character to vim. Arabic and
Hebrew are read and moved over, but laid out left to right, so an edit in
them selects the wrong text. Japanese and Korean on one line can be read as
one of the two. After an install or a macOS update, macOS compiles the
accurate read’s models once, which takes about a minute. Neru starts that as
it launches when a hotkey, hook or macro opens vim mode, and otherwise at the
first neru vim. It runs in a separate process, so moving around keeps
working meanwhile, and a card says what the wait is when vim mode opens
before it finishes.
Typing into the app re-sends each key, so an input method’s composition does
not work there, and i over text that cannot be edited sends the keys to the
app as shortcuts. Vim mode types every edit key by key too, so it refuses
an edit whose text has a character no key types, such as a letter outside
ASCII, and the status bar says why. A drag and every edit change the app’s
own selection. Vim mode also reads the window’s title and toolbar as text,
so an edit there, such as A on the title line, renames or types into it. Takes the vim flags in
the mode flag reference. The scope and appearance are
under [vim].
neru mode
Section titled “neru mode”neru mode <name> [flags]Enter a mode declared under [modes.<name>]. It
captures the keyboard, shows its indicator, and answers keys from its own
[modes.<name>.hotkeys] table. Escape returns to idle unless the table
rebinds it. The only flag is --toggle. An undeclared name is refused with
ERR_INVALID_INPUT. In a binding the step is "mode <name>".
Actions
Section titled “Actions”neru action <subcommand> [flags]One-shot input that runs without entering a mode. A subcommand refuses any
flag not listed in its own section with ERR_INVALID_INPUT, and the message
names the actions that accept it.
Targeting
Section titled “Targeting”Point-targeted actions use the active mode selection when one exists, and the cursor position otherwise.
| Flag | Type | Default | Description |
|---|---|---|---|
--selection | bool | false | Target the active mode selection. |
--bare | bool | false | Target the cursor position even when a mode selection exists. |
Action names
Section titled “Action names”These names work as a mode --action, in a hotkey binding, or after
neru action.
| Category | Names |
|---|---|
| Click | left_click, right_click, middle_click |
| Press | left_mouse_down, right_mouse_down, middle_mouse_down |
| Release | left_mouse_up, right_mouse_up, middle_mouse_up |
| Toggle | left_mouse_toggle, right_mouse_toggle, middle_mouse_toggle |
| Movement | move_mouse, move_mouse_relative, move_monitor, snap |
| Scroll | scroll ³, scroll_up, scroll_down, scroll_left, scroll_right, page_up, page_down, go_top, go_bottom |
| Mode | reset, backspace, move_cell, bisect, cycle_hint, refresh_hints, session_action, copy_text, search_hints ³, wait_for_mode_exit |
| Cursor | save_cursor_pos, restore_cursor_pos, hide_cursor, show_cursor |
| Keys | feed |
| Timing | sleep, in hotkey bindings only |
³ No neru action subcommand. search_hints opens the hint search field in
hints mode. Bind it as "action search_hints" in a mode’s [hotkeys], or run
it through neru run or neru macro. search_hints --confirm-on-label turns
on the hints flag of the same name for that one search. scroll takes no
flags. For one-shot scrolling use the directional names below.
A mode --action accepts only the click, press, release and toggle names,
move_mouse, and the deprecated mouse_down and mouse_up. Hints also
accepts copy_text on its own, without a chain or
--modifier. move_mouse
leaves the cursor on the selection and presses nothing, so a mode refuses
--modifier when every action in the chain is move_mouse. A chain with a
button keeps it, as in move_mouse,left_click --modifier cmd. A mode refuses
every other name with ERR_INVALID_INPUT.
neru action left_click, right_click, middle_click
Section titled “neru action left_click, right_click, middle_click”neru action left_click|right_click|middle_click [--modifier <mods>] [--selection] [--bare] [--state down|up] [--toggle]Press and release a mouse button, or one half of that.
| Flag | Type | Default | Description |
|---|---|---|---|
--modifier | string | Comma-separated modifiers held during the click: cmd, shift, alt, ctrl. | |
--state | string | down presses and holds, up releases. Without it, a full click. | |
--toggle | bool | false | Release the button if held, press and hold it otherwise. |
--selection, --bare | bool | false | See Targeting. |
--stateand--togglecannot be combined, and only these three subcommands accept them.- Neru releases held buttons when it returns to idle.
- A comma chain takes
--modifier,--selectionand--barewhen every action in it does. Neither a chain nor a mode--actiontakes--stateor--toggle, so use the action name instead.<button>_click --state downis<button>_mouse_down,--state upis<button>_mouse_up, and--toggleis<button>_mouse_toggle.
neru action left_click,left_click # double-clickmouse_down, mouse_up (deprecated)
Section titled “mouse_down, mouse_up (deprecated)”mouse_down and mouse_up are older spellings of left_mouse_down and
left_mouse_up. They still work, and the CLI prints a deprecation warning on
stderr naming the replacement.
neru action move_mouse
Section titled “neru action move_mouse”neru action move_mouse [--x <px>] [--y <px>] [--center] [--window] [--selection] [--bare]Move the cursor to an absolute position.
| Flag | Type | Default | Description |
|---|---|---|---|
--x, --y | int | 0 | Coordinates in pixels. With --center or --window, an offset. |
--center | bool | false | Target the center of the active screen. |
--window | bool | false | Target the center of the focused window. |
--selection, --bare | bool | false | See Targeting. |
neru action move_mouse --center --x 50 --y -30neru action move_mouse_relative
Section titled “neru action move_mouse_relative”neru action move_mouse_relative --dx <px> --dy <px>Move the cursor by a delta.
| Flag | Type | Default | Description |
|---|---|---|---|
--dx | int | Required. Pixels to move. Positive moves right. | |
--dy | int | Required. Pixels to move. Positive moves down. |
neru action move_monitor
Section titled “neru action move_monitor”neru action move_monitor [--name <name>] [--previous]Move the cursor to the next display. An active mode overlay follows it. With
one display connected, the action fails with ERR_INVALID_INPUT.
| Flag | Type | Default | Description |
|---|---|---|---|
--name | string | Target a display by name, case-insensitive, such as "DP-1". An unknown name fails with the list of available names. | |
--previous | bool | false | Cycle to the previous display instead. |
On Windows, displays that share a driver name get their device name as a
suffix, such as Generic PnP Monitor (DISPLAY5).
neru action snap
Section titled “neru action snap”neru action snap [--direction <dir>] [--role <roles>] [--text <terms>] [--strategy <name>] [--bare] [--json]Move the cursor onto the nearest element hints would label, or with
--direction onto the next one that way, without drawing labels or entering a
mode. It prints where the cursor landed and the element’s role.
| Flag | Type | Default | Description |
|---|---|---|---|
--direction | string | left, right, up or down. Step to the next element that way instead of the nearest one. | |
--role | string | Only snap to these roles, comma-separated, as hints --role takes them. Repeatable. | |
--text | string | Only snap to elements whose title, description or value contains one of these, comma-separated. Repeatable. | |
--strategy | string | axtree, vision, contour or segment. One value, no cycle list. Defaults to the strategy hints would use for the focused app. | |
--bare | bool | false | Ignore the mode’s region and search the active screen from the cursor. |
--json | bool | false | Print the answer as the action_snap object of the IPC schema. |
- Outside a mode, and in a mode that has not narrowed anything yet, it searches the active screen from the cursor.
- Once grid has a subgrid open, recursive_grid has zoomed in, or bisect has
cut, it searches that region from the selection. The cursor moves onto the
element and the mode’s selection moves with it, as with
move_mouse, so the next click aims at the element’s exact point rather than wherever the system last reported the cursor. The mode stays open. - Without
--direction, the element containing the starting point wins, the smallest first, so a button beats the row it sits in. Otherwise the nearest one wins. Vertical distance counts more than horizontal, by the region’s width over its height and between one and three times, so an element in the same row beats a slightly nearer one in the next. Pressing it again stays on the same element. - An element that holds others, such as a row, a list or a web page’s container, wins only when nothing smaller is in range. Clipped to a zoomed cell it covers, its center is the cell’s center, where the selection already is.
- With
--direction, it steps from the element under the cursor to the next one that way. An element only counts when its center lies past the current element’s edge, and never one around the cursor, such as the toolbar the button sits in. From an element that holds others, such as a toolbar’s empty space, it steps from the cursor itself. The gap across the direction costs more than the gap along it, much more for left and right, so it keeps to the same row or column over a nearer element beside it. Under[held_repeat]a held key keeps walking. - The cursor lands on the center of the part of the element inside the region,
and moves the way
move_mousedoes under[smooth_cursor]. Aselectevent with the actionsnapreports where. - Finding nothing leaves the cursor where it was and answers
ERR_ACTION_FAILED, and the rest of a binding still runs. In["action snap", "action left_click"]inside a grid mode the click lands on the grid’s selection, so a grid keeps working when detection finds nothing. Writeaction snap --bail-on-errorto stop instead, as Failure policy describes. - If you leave the mode, press a mode key, or run a cursor action such as
move_mouse_relativein the mode while it scans, the snap answersERR_CHAIN_BAIL, whether or not it found anything. That stops the binding, since you aimed the rest of it at a target you have left. - On Windows before Windows 10 version 2004 the screen capture includes Neru’s
own overlay, so snap refuses
vision,contourandsegmentwithERR_NOT_SUPPORTEDwhile a mode is open. On Linux the overlay disappears for the moment of the capture. Platform support has the detail.axtreeworks everywhere.
{"x":120,"y":120,"role":"ax:AXButton","source":"axtree","bounds":{"x":100,"y":100,"width":40,"height":40}}neru action move_cell
Section titled “neru action move_cell”neru action move_cell --direction left|right|up|down [--count <n>]Slide the active mode’s selection to a neighbouring cell on the same layer.
| Flag | Type | Default | Description |
|---|---|---|---|
--direction | string | Required. left, right, up or down. | |
--count | int | 1 | Cells to move, at least 1. |
- In recursive_grid, the region moves at the current depth and crosses into
the neighbouring parent at its edge. Once the grid has bottomed out at
max_depthormin_size_*, the final cell moves. - In grid, an open subgrid moves. Before a subgrid opens, nothing happens.
- Movement stops at the screen edge, applying as many steps as fit. Hints, scroll and idle ignore the action.
- With
[held_repeat]enabled, a key bound to it slides while held.[held_repeat]is off by default.
neru action scroll_up, scroll_down, scroll_left, scroll_right
Section titled “neru action scroll_up, scroll_down, scroll_left, scroll_right”neru action scroll_up|scroll_down|scroll_left|scroll_right [--modifier <mods>] [--steps <px>] [--selection] [--bare]Scroll one step in a direction.
| Flag | Type | Default | Description |
|---|---|---|---|
--modifier | string | Comma-separated modifiers held during the scroll: cmd, shift, alt, ctrl. | |
--steps | int | scroll.scroll_step | Scroll amount in pixels. |
--selection, --bare | bool | false | See Targeting. |
Most applications read a modified scroll as zoom. The bound key’s modifiers
are not added, so "Ctrl+K" = "action scroll_up" scrolls plain. Backend
support for --modifier is in the capability matrix.
neru action scroll_up --modifier ctrl # zoom inneru action page_up, page_down, go_top, go_bottom
Section titled “neru action page_up, page_down, go_top, go_bottom”neru action page_up|page_down|go_top|go_bottom [--modifier <mods>] [--selection] [--bare]Scroll by a page, or to the top or bottom. Flags are as for scroll_up,
without --steps. Page actions use scroll.scroll_step_half and
scroll.scroll_step_full. go_top and go_bottom scroll
scroll.scroll_step_full pixels, a million by default, so --modifier ctrl
on them sends a million pixels of zoom.
neru action feed
Section titled “neru action feed”neru action feed [--mode] <key> [<key>...]Send keystrokes to the focused application. Chords use +, such as
Cmd+Shift+P.
| Flag | Type | Default | Description |
|---|---|---|---|
--mode | bool | false | Route the keys through Neru’s active mode instead of the OS. |
Key names: a to z, 0 to 9, symbols such as =, -, [, ],
space, return, escape, tab, delete, left, right, up, down,
pageup, home, end, f1 to f24 (f21 to f24 on Linux and Windows
only), and modifiers such as cmd, shift, alt, ctrl, LeftCmd,
RightShift.
neru action bisect
Section titled “neru action bisect”neru action bisect --direction left|right|up|down|up_left|up_right|down_left|down_right [--count <n>]Keep a half or a quadrant of the region in bisect mode, and move the cursor to its center. Outside bisect mode the action does nothing.
| Flag | Type | Default | Description |
|---|---|---|---|
--direction | string | Required. One of the eight cuts. A hyphen may replace the underscore. | |
--count | int | 1 | Repeat the cut as one press, at least 1. |
- A cut on an axis already two pixels wide is refused. A count that would go below two pixels applies only the cuts that fit.
- One backspace undoes a whole counted press.
- A repeated cut reaches the outer slices only.
left --count 2keeps the left quarter, and the quarter from 25% to 50% isleftthenright.
neru action bisect --direction up_left --count 2neru action cycle_hint
Section titled “neru action cycle_hint”neru action cycle_hint [--backward]Move the hint selection without acting on it. Hints mode only.
| Flag | Type | Default | Description |
|---|---|---|---|
--backward | bool | false | Cycle to the previous hint. |
neru action refresh_hints
Section titled “neru action refresh_hints”neru action refresh_hintsRescan and redraw the labels with the flags the hints session was opened
with. Running the activation command again moves a --strategy or
--capture-scope cycle to its next value, or exits with --toggle. This
rescans with the value in use, and keeps the filters, action and --on-exit
steps. Hints mode only. It refuses a session opened with --targets, since
there is nothing to rescan. If the rescan finds nothing, hints mode exits and
the command fails.
[hints.hotkeys]"Ctrl+R" = "action refresh_hints"neru action session_action
Section titled “neru action session_action”neru action session_actionRun the action the hints session was opened with, holding its --modifier
and any sticky modifiers, at the cursor. The mode stays open. Use it as a step in a
[hints.select_with] entry. The
entry runs once the cursor is on the selected hint, so it can do what the
session does and then something more. Hints mode only. A session
opened without --action has nothing to run, so it does nothing there.
[hints.select_with]ctrl = ["action session_action", "idle"]neru action copy_text
Section titled “neru action copy_text”neru action copy_textCopy the text of the hint most recently selected to the clipboard. That is its
value, such as a field’s contents, else its title, such as a button’s or link’s
name, else its description. For a hint found by reading the screen, with the
vision, contour or segment strategy, it is the text recognized there. See
Platform support for how each
platform reads it.
Use it as a step in a
[hints.select_with] entry or a
binding’s --on-exit, or as the hints mode’s --action, which copies the hint
you type without clicking it:
[hotkeys]"Primary+Shift+Y" = "hints --action copy_text"
[hints.select_with]"ctrl+alt" = ["action copy_text", "idle"]- It fails with
ERR_INVALID_INPUTwhen no hint has been selected since a mode last opened, and withERR_ACTION_FAILEDwhen the hint has no text. As the mode’s--action, a copy that fails closes hints as canceled and runs no--on-exit. - It never copies a password field’s text.
- On Linux it needs a clipboard tool, listed in
Linux setup. Without one it fails with
ERR_NOT_SUPPORTEDand names the tools. - To use the text in a command, copy it first and read the clipboard, as in
["action copy_text", 'exec say "$(pbpaste)"'].
neru action wait_for_mode_exit
Section titled “neru action wait_for_mode_exit”neru action wait_for_mode_exit [--bail]Block an action chain until the current mode exits.
| Flag | Type | Default | Description |
|---|---|---|---|
--bail | bool | false | Abort the chain with ERR_CHAIN_BAIL if the mode exits with no selection. |
neru action reset, backspace
Section titled “neru action reset, backspace”neru action resetneru action backspacereset clears the mode’s input. backspace deletes hints or grid input,
closes a grid subgrid, or backtracks recursive_grid.
neru action save_cursor_pos, restore_cursor_pos, hide_cursor, show_cursor
Section titled “neru action save_cursor_pos, restore_cursor_pos, hide_cursor, show_cursor”neru action save_cursor_pos [--slot <name>]neru action restore_cursor_pos [--slot <name>]neru action hide_cursorneru action show_cursorSave, restore, hide or show the cursor. hide_cursor and show_cursor are
macOS only, and Linux and Windows refuse them with ERR_NOT_SUPPORTED.
| Flag | Type | Default | Description |
|---|---|---|---|
--slot | string | default | Named slot to save into or restore from. |
Cursor slots
Section titled “Cursor slots”- A slot name starts with a letter, then letters, digits, underscores and dashes.
- Restoring consumes the slot. A second restore succeeds and moves nothing.
- Give a macro its own slot so it does not overwrite the caller’s saved position.
neru status --jsonreports occupied slots undersaved_cursor_slots.
[macros]peek = ["action save_cursor_pos --slot peek", "action move_mouse --x 0 --y 0", "action left_click", "action restore_cursor_pos --slot peek"]action sleep (hotkey bindings only)
Section titled “action sleep (hotkey bindings only)”"action sleep <duration>"Pause between steps of a hotkey action array. <duration> is seconds as a
plain number (0.2), or takes a ms or s unit. There is no
neru action sleep, and the shell refuses it with ERR_INVALID_INPUT.
sleep must be its own array entry, and config validation refuses it in a
comma chain such as action left_click,sleep.
[hotkeys]"Return" = ["action left_click", "action sleep 500ms", "hints"]Sequences
Section titled “Sequences”neru run
Section titled “neru run”neru run [--stop-on-error] <step> [step...]Run several steps in order in one call, with the executor that runs hotkey
arrays and --on-exit. Each step is written as in a hotkey binding: an
action, a mode, exec <command>, or macro <name> [arg...] from
[macros].
| Flag | Type | Default | Description |
|---|---|---|---|
--stop-on-error | bool | false | End at the first failing step, as if every step carried --bail-on-error. |
- The CLI refuses a blank step. Over IPC, the daemon drops blank steps, and
refuses only a request with no steps left, with
ERR_INVALID_INPUT. action wait_for_mode_exit --bailafter a canceled mode ends the sequence withERR_CHAIN_BAIL.- Neru reports a failing step and still runs the rest. The command fails with
ERR_ACTION_FAILEDnaming the first failure. - A sequence may start another sequence, up to five levels deep. Neru refuses
one nested deeper with
ERR_INVALID_INPUTbefore any of its steps run, and the sequence that started it counts that as one failed step. - A sequence with sleeps or
wait_for_mode_exitcan outlast the 10-second IPC timeout. Raise it with--timeout, or bind the sequence to a hotkey, which runs with no caller waiting.
neru run "action save_cursor_pos" "hints --action left_click" \ "action wait_for_mode_exit --bail" "action restore_cursor_pos"Failure policy
Section titled “Failure policy”End a step with --bail-on-error to stop the sequence if that step fails. It
must be the last word of the step, and the daemon removes it before running
the step. It works in hotkey arrays, --on-exit and neru run.
[hints.hotkeys]"Shift+L" = ["action left_click --bail-on-error", "idle"]- Text that only looks like the directive, as in
exec sh -c "echo --bail-on-error", passes through to the shell. - A nested
runormacrokeeps its own policy inside, and its failure counts as one failed step to the caller. - The error names the step that stopped the sequence, and says whether later steps ran.
neru macro
Section titled “neru macro”neru macro <name> [arg...]Run a named sequence from [macros], as a binding’s
macro <name> step would. Arguments fill $1, $2 and so on, and their
count must match the highest placeholder. Each shell argument passes through
unchanged, so "hello there" needs no extra quoting.
Response codes match neru run, plus ERR_INVALID_INPUT for an
unknown macro or a wrong argument count. Raise --timeout for long macros.
neru macro say_it "hello there"Configuration commands
Section titled “Configuration commands”Every option is in Configuration.
neru config init
Section titled “neru config init”neru config init [-f] [-c <path>]Write a default config file.
| Flag | Shorthand | Type | Default | Description |
|---|---|---|---|---|
--force | -f | bool | false | Overwrite an existing file. |
--config | -c | string | "" | Write to this path. |
neru config validate
Section titled “neru config validate”neru config validate [-c <path>]Check a config file for syntax errors and invalid values, including the mode flags in your bindings. Exits successfully when no config file exists.
A setting that loads but will not take effect is a warning. So is a
deprecated setting, which works until it is removed. The command still
succeeds. Examples are grid --search, a clickable role this platform has no
name for, or hints.on_mission_control_activated. Global hotkeys
lists which mistakes warn and which refuse the file.
Configuration is valid, with warnings:
hotkeys.Primary+Shift+G: grid does not accept --search
These parts of the configuration load. Each one will not take effect or is deprecated, so change it as its line says.neru config set
Section titled “neru config set”neru config set [--no-reload] <key> <value>Change a value on the running daemon. The change applies at once and is saved
to the override file.
<key> is a dotted TOML path, such as hints.strategy. neru config dump
prints the whole configuration as nested JSON, where each path is a chain of
keys.
| Flag | Type | Default | Description |
|---|---|---|---|
--no-reload | bool | false | Skip hotkey re-registration and mode exit. Run neru config reload after the last of several dependent changes. |
Values: a string "asdfghjkl", integer 14, boolean true, float 0.5,
color "#FF0000AA" or {"light":"#000","dark":"#FFF"}, or array
"button,link" or '["button","link"]'.
A list of steps, such as a hook, is never split at commas, because a step can
contain one. Give one step as is, 'exec echo a,b', or several as a TOML
array, '["exec echo a,b", "idle"]'.
Setting several dependent values with --no-reload is shown in
Configuring Neru.
The CLI checks the key and the value before it sends them, so a bad one fails with the field’s type and no response code.
Errors: ERR_ACTION_FAILED when the daemon cannot apply or save the change.
neru config reset
Section titled “neru config reset”neru config reset [--no-reload] <key>Remove a key from the override file, and reload so it reverts to the base config or the built-in default. To remove every override at once, see How the layers combine.
| Flag | Type | Default | Description |
|---|---|---|---|
--no-reload | bool | false | Skip the reload. Run neru config reload after the last of several resets. |
Errors: ERR_INVALID_INPUT for an unknown key, ERR_ACTION_FAILED when the
override file cannot be changed or the reload fails.
neru config dump
Section titled “neru config dump”neru config dumpPrint the configuration the daemon runs on as JSON, under the key names
config.toml uses. It is your file, its overrides and the defaults, merged.
The output matches the config schema.
neru config reload
Section titled “neru config reload”neru config reloadReload the config from disk. Some settings, such as systray.enabled, need a
daemon restart.
Runtime toggles
Section titled “Runtime toggles”Each toggle lasts until the daemon restarts, and answers while Neru is stopped. All three take one flag.
| Flag | Type | Default | Description |
|---|---|---|---|
--state | string | toggle | on or off sets the state whatever it was, and toggle flips it. |
Scripts should use on or off, and read the result from
neru status --json. The CLI prints the reply as a line of text. Over IPC the
reply also carries the new state in data, whose keys are in the
IPC Commands table.
Errors: a --state value other than these three fails. The CLI refuses it
before sending, and the daemon answers ERR_INVALID_INPUT.
neru toggle-scroll-invert
Section titled “neru toggle-scroll-invert”neru toggle-scroll-invert [--state on|off|toggle]Invert the scroll direction, overriding scroll.invert_scroll. Also in the
systray menu. Reported as scroll_inverted.
neru toggle-cursor-follow-selection
Section titled “neru toggle-cursor-follow-selection”neru toggle-cursor-follow-selection [--state on|off|toggle]Toggle whether the real cursor follows the selection in the active hints,
grid, recursive_grid or bisect session. In any other mode, idle included, it
fails with ERR_INVALID_INPUT, even with --state. Reported as
cursor_follow_selection.
neru toggle-screen-share
Section titled “neru toggle-screen-share”neru toggle-screen-share [--state on|off|toggle]Hide overlays from screen sharing while keeping them visible locally.
--state on hides, matching hidden_for_screen_share. macOS and Windows can
hide the overlay from a screen share. On Linux the command fails with
ERR_NOT_SUPPORTED and changes nothing. On Windows it needs Windows 10 version
2004 or later, and it also leaves the overlay out of screenshots and
recordings. On
macOS Neru uses the deprecated NSWindow.sharingType API:
| macOS version | Behavior |
|---|---|
| 14 and older | Reliable |
| 15.0 to 15.3 | Partially effective |
| 15.4 and newer | Limited to ScreenCaptureKit-based apps |
Utilities
Section titled “Utilities”neru roles
Section titled “neru roles”neru roles [--explain] [--json] [-c <path>]List the roles accepted by hints.clickable_roles and neru hints --role,
and how each resolves on this platform. A role is a semantic name such as
button, or a native role with a prefix. Entries prefixed for another
platform are ignored, so one config serves several machines.
| Prefix | Platform | Example |
|---|---|---|
ax: | macOS Accessibility | ax:AXDisclosureTriangle |
atspi: | Linux AT-SPI | atspi:page tab list |
uia: | Windows UI Automation | uia:Custom |
| Flag | Type | Default | Description |
|---|---|---|---|
--explain | bool | false | Resolve the loaded config entry by entry, showing each entry’s native roles and which do not apply here. |
--json | bool | false | Print the answer as one JSON object. |
With --json, the object goes to stdout alone, and errors go to stderr with a
non-zero exit status. Every key is stable.
| Key | Type | Description |
|---|---|---|
platform | string | The OS the roles resolve on: darwin, linux or windows. |
vocabulary | string | The native vocabulary here: ax, atspi or uia. Empty with no accessibility backend. |
roles | array | One object per semantic role. semantic is its name, and native lists its native roles here. subrole is true when macOS reports those names as an element’s subrole. |
With --explain --json, the keys are:
| Key | Type | Description |
|---|---|---|
platform | string | As above. |
config | string | Path of the config file resolved, empty for the built-in defaults. |
entries | array | One object per hints.clickable_roles entry, in order. entry is the entry as written, and vocabulary its prefix, empty for a semantic name. native lists the native roles it adds here. ignored says why it adds none, and is empty when it applies. |
native | array | Every native role the entries select, once each. |
neru describe
Section titled “neru describe”neru describe [--json]List every mode, mode flag, action, config option, event and hook variable
this build reads, with the platforms each one does something on. It describes
the binary, so it needs no daemon and no config. The daemon answers the same
object to the IPC command describe.
Without --json it prints the counts and each word that does nothing on this
platform, with the reason. With --json it prints the whole object, which
describe in the IPC schema defines.
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | Print the whole description as one JSON object. |
| Key | Type | Description |
|---|---|---|
version | string | The build’s version, as neru --version prints it. |
protocol | integer | The IPC protocol this build speaks. |
platform | string | darwin, linux or windows, empty on a build Neru declares nothing about. |
modes | array | Every built-in mode, named as neru status and NERU_MODE name it. Declared modes are in the config. |
mode_flags | array | One object per mode flag: name, short, shape (presence, value or list), the modes that take it, and usage. |
actions | array | One object per action name. modes lists the modes whose --action can run it, and is empty for an action that runs only on its own. |
options | array | One object per config key, as its full TOML path. Its type and default are in neru schema config. |
events | array | One object per event, as neru watch names it: the hook that runs on it, a description, and the variables its hook sees. |
variables | array | One object per hook variable, with its name and the value it holds. |
Every object in mode_flags, actions, options and events also carries
platforms, the platforms it does something on, here, whether it does on
this machine, and note, which says why platforms is short and is empty when
it is not. mode_flags and options carry values too, listing each value
that works on fewer platforms than the word itself. The text of usage,
description, value and note may change in any release.
neru describe --json | jq -r '.actions[] | select(.here) | .name'neru schema
Section titled “neru schema”neru schema ipc|configPrint the IPC schema (ipc) or the
config schema (config) this build speaks,
the same file the repository publishes for its version. It needs no daemon and
fetches nothing.
neru agent-guide
Section titled “neru agent-guide”neru agent-guidePrint a short guide for an AI agent or a program that drives Neru: how to learn what this build accepts, read its state, drive it and change its config, and the rules a tool built on it follows. It names this build’s version, protocol and docs, so an agent can read it instead of docs for another release. It needs no daemon.
neru services
Section titled “neru services”neru services install|uninstall|start|stop|restartneru services status [--json]Manage Neru as a login service. If a package manager such as Nix, Homebrew or home-manager manages the service, use that tool instead.
install writes the service definition and enables it for login, and
uninstall disables and removes it. stop stops the service and disables it,
so it stays stopped across logins until start, which enables it again and
starts it. The definition stays installed. restart restarts a running service
and refuses a stopped one, saying to run start. status reports whether it is
installed and running.
| Platform | Definition | Notes |
|---|---|---|
| macOS | launchd plist in ~/Library/LaunchAgents | install refuses if a plist exists, so run uninstall first. stop runs launchctl disable and bootout, and restart runs launchctl kickstart -k. status reports a stopped service as stopped. For where its output goes, see Log file locations. |
| Linux | systemd user unit | See Linux setup. |
| Windows | Task Scheduler task \Neru, logon trigger | Runs neru launch as you with an interactive token, restarts on failure, no time limit, no admin rights. status reads the task state (running, ready, queued, disabled). stop works like schtasks /Change /DISABLE followed by schtasks /End. |
On Linux and Windows, every subcommand but status refuses to touch a unit or
task Neru did not write. status on a machine without the service reports that
rather than failing.
| Flag | Type | Default | Description |
|---|---|---|---|
--json | bool | false | status only. Print the answer as one JSON object. |
neru services status --json exits 0 whatever the service is doing. Every
key is stable.
| Key | Type | Description |
|---|---|---|
supported | bool | Whether this machine has the service manager Neru drives. false on Linux without systemd. |
installed | bool | Whether the service is installed. |
running | bool | Whether the daemon the service starts is running. |
starts_at_login | bool | Whether the service starts Neru at login. neru services stop turns it off. |
message | string | The line neru services status prints without --json. |
error | string | Why the state could not be read, empty when it was. When set, the booleans say nothing. |
neru docs
Section titled “neru docs”neru docs config|cliOpen the configuration reference (config, or its alias configuration) or
this page (cli) with the desktop’s default handler. URLs point at the tag of the installed version, or
main for development builds.