Skip to content

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.

FlagShorthandTypeDefaultDescription
--config-cstring""Config file path. Overrides the default search paths. See Config file location.
--timeoutint10IPC 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.

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

Resume mode switching and overlay rendering after neru stop.

Errors: ERR_ALREADY_RUNNING when Neru is not stopped.

neru stop

Disable 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

Exit the active mode. Does nothing when no mode is active. Takes no flags or arguments, and refuses anything written after it.

neru status [--json]

Print the daemon state and the current mode.

FlagTypeDefaultDescription
--jsonboolfalsePrint 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.

KeyTypeDescription
enabledboolfalse after neru stop, true after neru start.
modestringThe active mode, same values as Mode.
configstringPath of the config file in use.
hints_enabled, grid_enabled, recursive_grid_enabled, bisect_enabledboolWhether each mode is enabled in the config.
scroll_invertedboolSet by toggle-scroll-invert.
hidden_for_screen_shareboolSet by toggle-screen-share. true means hidden. Always false on Linux, where nothing hides the overlay.
cursor_follow_selectionbool or nullSet 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_slotsobjectThe occupied cursor slots, each {"x": …, "y": …}. Empty when none are saved.
sticky_modifiersstringThe sticky modifiers held, such as cmd,shift. Empty when none is.
capabilitiesobjectPer-subsystem support on this platform, as neru doctor reports it.
profileobjectWhich 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 [--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.

FlagTypeDefaultDescription
--eventstringnonePrint 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.

KeyPresent onValue
seqevery lineRises by one with each event. On a snapshot, the seq of the last event it includes. With --event, it skips the events left out.
eventevery linesnapshot, or the event, such as mode_enter
statussnapshotThe neru status --json object
modemode_enter, mode_exit, selectThe mode, named as neru status names it
reasonmode_exitcompleted, 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
actionselect, and mode_exit when completedThe 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_idapp_focusThe application, as bundle_id names it
okconfig_reloadtrue or false
onscroll_invert, screen_share_hideThe state switched to, as scroll_inverted and hidden_for_screen_share report it
slotcursor_save, cursor_restoreThe cursor slot
x, ycursor_save, selectThe position saved, or the point selected or snapped to
modifierssticky_modifiersThe set held now, as sticky_modifiers reports it
monitormonitor_moveThe display moved to, as move_monitor --name takes it
droppeda snapshot after missed eventsHow 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 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.

FlagTypeDefaultDescription
--jsonboolfalsePrint 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}]}
KeyTypeDescription
namestringThe name move_monitor --name takes. Two identical monitors can share one.
x, y, width, heightintThe display’s bounds.
scalenumberPhysical 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}
KeyTypeDescription
x, yintThe cursor position.
displaystring or nullThe display’s name, as query displays lists it. null when no display holds the cursor.
display_indexint or nullThe 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}
KeyTypeDescription
x, y, width, heightintThe window’s bounds.

neru query app prints the focused application. Run from a terminal, it reports the terminal, so give yourself time to switch:

Terminal window
sleep 3; neru query app
{"bundle_id":"com.apple.Safari"}
KeyTypeDescription
bundle_idstringThe 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.

FlagTypeDefaultDescription
--rolestring, repeatablenoneOnly these roles.
--textstring, repeatablenoneOnly elements whose text contains one of these.
--strategystringhints.strategyHow to find elements.
--capture-scopestringhints.capture_scopeRegion vision, contour and segment scan.
--split-wordboolfalseOne element per word of detected text. Needs vision.
--label-directionstringhints.label_directionLabel 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}]}
KeyTypeDescription
labelstringThe label neru hints with the same flags would draw on the element now.
rolestringThe native role, spelled as --role takes it, such as ax:AXButton.
title, description, valuestringThe element’s text. --text matches any of the three. Empty when the element has none.
sourcestringWhat 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.
identifierstringThe 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.
focusedboolWhether the element has keyboard focus.
x, y, width, heightintThe 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:

  1. Run neru query hints with the flags you need, and read the label.
  2. Start hints mode with exactly the same flags, plus --action.
  3. Type the label into the mode with neru action feed --mode, one key per character, before the screen changes.
Terminal window
label=$(neru query hints --text Save --json | jq -r '.hints[0].label')
neru hints --text Save --action left_click
neru action feed --mode $(echo "$label" | fold -w1)
neru doctor [--json]

Report config validity, socket health, platform capabilities from the capability matrix, and component state.

FlagTypeDefaultDescription
--jsonboolfalsePrint every check as one JSON object.
  • With the daemon running, the Overlay backend line names the renderer in use. On Windows it tells DirectComposition + Direct2D from the GDI fallback and says why the fallback was taken.
  • The platform_support row 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 stop still 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.

KeyTypeDescription
healthyboolfalse exactly when the command exits non-zero.
configobjectpath 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_rolesobjectHow 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_supportobject or nullinert 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_endpointobjectpath is where the daemon listens, empty when Neru cannot determine it for this user. reachable is whether the daemon answers there.
daemonobject or nullThe 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.

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.

  • --action takes the mouse-button action names or move_mouse, and in hints also copy_text. --on-exit steps form one action sequence. hints --action move_mouse --on-exit scroll opens scroll mode on the hint you pick.
  • --role takes the neru roles vocabulary. --label-direction is explained in Choosing a label direction.
  • A flag left out takes its config value: --strategy from hints.strategy, --label-direction from hints.label_direction. --cursor-selection-mode defaults to follow.

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 --toggle opens on axtree, steps to contour, then closes.
  • Each value may appear once.
  • Only one flag per command may take a list.
  • --split-word refuses a --strategy list.

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.

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.

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.

Shorthand -r. Takes no value. Modes: hints · grid · recursive_grid.

Reopen the mode after the action runs. Needs —action.

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.

Shorthand -s. Takes no value. Modes: hints.

Open with the hint search field showing.

Takes no value. Modes: hints.

Hide every hint until the search has text. Needs —search.

Takes no value. Modes: hints.

Confirm the search as soon as a label typed after the search text leaves one match, without Return.

Takes no value. Modes: hints.

Exit when a key matches no hint.

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.

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.

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.

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.

Takes a value. Modes: hints.

Label order: normal (shorter labels first) or reverse (spread across the alphabet).

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.

Takes no value. Modes: hints.

Hint each word of detected text separately. Needs the vision strategy.

Takes no value. Modes: grid.

Select a cell’s center as soon as its label is typed, without opening the subgrid.

Takes a value. Modes: recursive_grid.

Open recursive grid already zoomed to this depth at the cursor.

Takes a value. Modes: hints · grid · recursive_grid · bisect · vim.

Whether the real cursor follows the selection (follow) or stays put (hold).

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 [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.

Terminal window
neru hints --action left_click --role button --text submit

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.

Terminal window
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 vision strategy finds.
  • --targets refuses --role, --text, --strategy, --capture-scope, --split-word and --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 [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].

Terminal window
neru grid --action left_click --on-exit 'exec notify-send clicked'
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.

Terminal window
neru recursive_grid --zoom-to-depth 3 --action left_click
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 [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 [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 [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.

KeysDoes
i, a, I, A, o, OClick the app’s caret into place, then type into the app until Escape
c, d, x, r, J and the restSelect the text, then erase it or type over it
p, PClick into place and type the register’s text, without its □ icons. Vim mode never touches the clipboard
u, Ctrl+RThe 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 + motionCopy the text as read, without touching the app. The copied text flashes and the status bar says how much
Return, gc, gr, gmClick 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, :movemouseMove 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 modeDrag across the text so the app selects it, then leave. Works on text that cannot be edited
s + characters + labelType 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, [iMove to the next or the previous icon, with a count to skip
Ctrl+W + h, j, k, lMove to the container left, below, above or right, within the block the cursor is in until that block ends
Ctrl+W + w, WMove to the next or the previous container
ic, acThe 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+YScroll 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, zLScroll the app left or right eight characters, or the count with one, or half the width read with zH and zL
zzScroll 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+LRead the screen again, keeping registers, macros and the last search
:sReplace 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
:qLeave
:leftclick, :rightclick, :middleclick + optional numberClick at the cursor that many times, once without one, as :leftclick 2
:leftdown, :leftup, :rightdown, :rightup, :middledown, :middleupPress or release the button at the cursor, so a motion between them drags. Leaving the mode releases a button still held
Tab, Shift+TabOn 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
EscapeCancel 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 reads 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 <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>".

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.

Point-targeted actions use the active mode selection when one exists, and the cursor position otherwise.

FlagTypeDefaultDescription
--selectionboolfalseTarget the active mode selection.
--bareboolfalseTarget the cursor position even when a mode selection exists.

These names work as a mode --action, in a hotkey binding, or after neru action.

CategoryNames
Clickleft_click, right_click, middle_click
Pressleft_mouse_down, right_mouse_down, middle_mouse_down
Releaseleft_mouse_up, right_mouse_up, middle_mouse_up
Toggleleft_mouse_toggle, right_mouse_toggle, middle_mouse_toggle
Movementmove_mouse, move_mouse_relative, move_monitor, snap
Scrollscroll ³, scroll_up, scroll_down, scroll_left, scroll_right, page_up, page_down, go_top, go_bottom
Modereset, backspace, move_cell, bisect, cycle_hint, refresh_hints, session_action, copy_text, search_hints ³, wait_for_mode_exit
Cursorsave_cursor_pos, restore_cursor_pos, hide_cursor, show_cursor
Keysfeed
Timingsleep, 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.

FlagTypeDefaultDescription
--modifierstringComma-separated modifiers held during the click: cmd, shift, alt, ctrl.
--statestringdown presses and holds, up releases. Without it, a full click.
--toggleboolfalseRelease the button if held, press and hold it otherwise.
--selection, --bareboolfalseSee Targeting.
  • --state and --toggle cannot be combined, and only these three subcommands accept them.
  • Neru releases held buttons when it returns to idle.
  • A comma chain takes --modifier, --selection and --bare when every action in it does. Neither a chain nor a mode --action takes --state or --toggle, so use the action name instead. <button>_click --state down is <button>_mouse_down, --state up is <button>_mouse_up, and --toggle is <button>_mouse_toggle.
Terminal window
neru action left_click,left_click # double-click

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 [--x <px>] [--y <px>] [--center] [--window] [--selection] [--bare]

Move the cursor to an absolute position.

FlagTypeDefaultDescription
--x, --yint0Coordinates in pixels. With --center or --window, an offset.
--centerboolfalseTarget the center of the active screen.
--windowboolfalseTarget the center of the focused window.
--selection, --bareboolfalseSee Targeting.
Terminal window
neru action move_mouse --center --x 50 --y -30
neru action move_mouse_relative --dx <px> --dy <px>

Move the cursor by a delta.

FlagTypeDefaultDescription
--dxintRequired. Pixels to move. Positive moves right.
--dyintRequired. Pixels to move. Positive moves down.
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.

FlagTypeDefaultDescription
--namestringTarget a display by name, case-insensitive, such as "DP-1". An unknown name fails with the list of available names.
--previousboolfalseCycle 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 [--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.

FlagTypeDefaultDescription
--directionstringleft, right, up or down. Step to the next element that way instead of the nearest one.
--rolestringOnly snap to these roles, comma-separated, as hints --role takes them. Repeatable.
--textstringOnly snap to elements whose title, description or value contains one of these, comma-separated. Repeatable.
--strategystringaxtree, vision, contour or segment. One value, no cycle list. Defaults to the strategy hints would use for the focused app.
--bareboolfalseIgnore the mode’s region and search the active screen from the cursor.
--jsonboolfalsePrint 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_mouse does under [smooth_cursor]. A select event with the action snap reports 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. Write action snap --bail-on-error to stop instead, as Failure policy describes.
  • If you leave the mode, press a mode key, or run a cursor action such as move_mouse_relative in the mode while it scans, the snap answers ERR_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, contour and segment with ERR_NOT_SUPPORTED while a mode is open. On Linux the overlay disappears for the moment of the capture. Platform support has the detail. axtree works everywhere.
{"x":120,"y":120,"role":"ax:AXButton","source":"axtree","bounds":{"x":100,"y":100,"width":40,"height":40}}
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.

FlagTypeDefaultDescription
--directionstringRequired. left, right, up or down.
--countint1Cells 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_depth or min_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.

FlagTypeDefaultDescription
--modifierstringComma-separated modifiers held during the scroll: cmd, shift, alt, ctrl.
--stepsintscroll.scroll_stepScroll amount in pixels.
--selection, --bareboolfalseSee 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.

Terminal window
neru action scroll_up --modifier ctrl # zoom in

neru 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 [--mode] <key> [<key>...]

Send keystrokes to the focused application. Chords use +, such as Cmd+Shift+P.

FlagTypeDefaultDescription
--modeboolfalseRoute 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 --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.

FlagTypeDefaultDescription
--directionstringRequired. One of the eight cuts. A hyphen may replace the underscore.
--countint1Repeat 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 2 keeps the left quarter, and the quarter from 25% to 50% is left then right.
Terminal window
neru action bisect --direction up_left --count 2
neru action cycle_hint [--backward]

Move the hint selection without acting on it. Hints mode only.

FlagTypeDefaultDescription
--backwardboolfalseCycle to the previous hint.
neru action refresh_hints

Rescan 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

Run 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

Copy 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_INPUT when no hint has been selected since a mode last opened, and with ERR_ACTION_FAILED when 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_SUPPORTED and 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 [--bail]

Block an action chain until the current mode exits.

FlagTypeDefaultDescription
--bailboolfalseAbort the chain with ERR_CHAIN_BAIL if the mode exits with no selection.
neru action reset
neru action backspace

reset 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_cursor
neru action show_cursor

Save, restore, hide or show the cursor. hide_cursor and show_cursor are macOS only, and Linux and Windows refuse them with ERR_NOT_SUPPORTED.

FlagTypeDefaultDescription
--slotstringdefaultNamed slot to save into or restore from.
  • 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 --json reports occupied slots under saved_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 <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"]
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].

FlagTypeDefaultDescription
--stop-on-errorboolfalseEnd 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 --bail after a canceled mode ends the sequence with ERR_CHAIN_BAIL.
  • Neru reports a failing step and still runs the rest. The command fails with ERR_ACTION_FAILED naming the first failure.
  • A sequence may start another sequence, up to five levels deep. Neru refuses one nested deeper with ERR_INVALID_INPUT before 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_exit can outlast the 10-second IPC timeout. Raise it with --timeout, or bind the sequence to a hotkey, which runs with no caller waiting.
Terminal window
neru run "action save_cursor_pos" "hints --action left_click" \
"action wait_for_mode_exit --bail" "action restore_cursor_pos"

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 run or macro keeps 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 <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.

Terminal window
neru macro say_it "hello there"

Every option is in Configuration.

neru config init [-f] [-c <path>]

Write a default config file.

FlagShorthandTypeDefaultDescription
--force-fboolfalseOverwrite an existing file.
--config-cstring""Write to this path.
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 [--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.

FlagTypeDefaultDescription
--no-reloadboolfalseSkip 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 [--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.

FlagTypeDefaultDescription
--no-reloadboolfalseSkip 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

Print 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

Reload the config from disk. Some settings, such as systray.enabled, need a daemon restart.

Each toggle lasts until the daemon restarts, and answers while Neru is stopped. All three take one flag.

FlagTypeDefaultDescription
--statestringtoggleon 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 [--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 [--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 [--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 versionBehavior
14 and olderReliable
15.0 to 15.3Partially effective
15.4 and newerLimited to ScreenCaptureKit-based apps
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.

PrefixPlatformExample
ax:macOS Accessibilityax:AXDisclosureTriangle
atspi:Linux AT-SPIatspi:page tab list
uia:Windows UI Automationuia:Custom
FlagTypeDefaultDescription
--explainboolfalseResolve the loaded config entry by entry, showing each entry’s native roles and which do not apply here.
--jsonboolfalsePrint 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.

KeyTypeDescription
platformstringThe OS the roles resolve on: darwin, linux or windows.
vocabularystringThe native vocabulary here: ax, atspi or uia. Empty with no accessibility backend.
rolesarrayOne 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:

KeyTypeDescription
platformstringAs above.
configstringPath of the config file resolved, empty for the built-in defaults.
entriesarrayOne 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.
nativearrayEvery native role the entries select, once each.
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.

FlagTypeDefaultDescription
--jsonboolfalsePrint the whole description as one JSON object.
KeyTypeDescription
versionstringThe build’s version, as neru --version prints it.
protocolintegerThe IPC protocol this build speaks.
platformstringdarwin, linux or windows, empty on a build Neru declares nothing about.
modesarrayEvery built-in mode, named as neru status and NERU_MODE name it. Declared modes are in the config.
mode_flagsarrayOne object per mode flag: name, short, shape (presence, value or list), the modes that take it, and usage.
actionsarrayOne 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.
optionsarrayOne object per config key, as its full TOML path. Its type and default are in neru schema config.
eventsarrayOne object per event, as neru watch names it: the hook that runs on it, a description, and the variables its hook sees.
variablesarrayOne 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.

Terminal window
neru describe --json | jq -r '.actions[] | select(.here) | .name'
neru schema ipc|config

Print 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

Print 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 install|uninstall|start|stop|restart
neru 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.

PlatformDefinitionNotes
macOSlaunchd plist in ~/Library/LaunchAgentsinstall 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.
Linuxsystemd user unitSee Linux setup.
WindowsTask Scheduler task \Neru, logon triggerRuns 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.

FlagTypeDefaultDescription
--jsonboolfalsestatus only. Print the answer as one JSON object.

neru services status --json exits 0 whatever the service is doing. Every key is stable.

KeyTypeDescription
supportedboolWhether this machine has the service manager Neru drives. false on Linux without systemd.
installedboolWhether the service is installed.
runningboolWhether the daemon the service starts is running.
starts_at_loginboolWhether the service starts Neru at login. neru services stop turns it off.
messagestringThe line neru services status prints without --json.
errorstringWhy the state could not be read, empty when it was. When set, the booleans say nothing.
neru docs config|cli

Open 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.