Skip to content

IPC protocol

The wire format between the neru CLI and the daemon. Use it to drive Neru without spawning the neru binary. For most scripts, calling neru is simpler, see Scripting.

Each call sends one JSON request and reads one JSON response, except a stream, which keeps sending lines after it. The request needs no newline after it. The daemon ends the response, and each stream line, with one.

The endpoint is private to your user:

PlatformEndpoint
macOS and Linux$XDG_RUNTIME_DIR/neru/neru.sock, else $TMPDIR/neru-<uid>/neru.sock
WindowsThe named pipe \\.\pipe\neru-<SID>

When $XDG_RUNTIME_DIR is unset, Neru uses /run/user/<uid> in its place if that directory exists, as it does in a Linux login session. $TMPDIR falls back to /tmp. The neru CLI looks in both places. To check the path a client should dial, read ipc_endpoint.path from neru doctor --json. The daemon prints its endpoint at startup. It queues commands, so concurrent calls are safe.

{ "action": "hints", "args": ["--action=left_click"], "protocol": 1 }
FieldTypeDescription
actionstringRequired. The command.
argsstring[]The command’s arguments, written as a user types them after neru.
protocolintThe protocol the client needs. The daemon refuses a higher number than its own with ERR_VERSION_MISMATCH.
versionstringThe neru binary’s build version. The daemon refuses any other build with ERR_VERSION_MISMATCH. Other clients leave it out.

The daemon refuses a field it does not know with ERR_INVALID_INPUT.

A request may be at most 64 KiB. The daemon refuses a larger one with ERR_INVALID_INPUT. It waits 30 seconds after you connect for the request, then drops the connection.

{ "protocol": 1, "success": true, "message": "OK", "code": "OK" }
FieldTypeDescription
protocolintThe protocol the daemon speaks.
successboolWhether the command did what it was asked.
codestringOne of the response codes.
messagestringA sentence for people. Branch on code, never on this.
dataanyThe command’s payload, when it has one, such as the status object.
versionstringThe daemon’s build version.

Every response carries protocol, the version of this contract the daemon speaks. It is 1.

Within one protocol, the request and response fields, the response codes, the command names, and the data keys documented here and in the CLI reference keep their names, types and meaning. Not covered:

  • The message text.
  • The version string.
  • The contents of capabilities, profile and components.
  • The wording of the prose fields in describe: usage, description, value and note.
  • Anything this page and the CLI reference do not document.

A protocol can gain commands, flags, data keys, events and response codes, so ignore keys and events you do not know. Only a change that breaks a client raises the number, and only a major Neru release makes one. Neru 2 is protocol 2, which removes the action names mouse_down and mouse_up.

Writing a client:

  • Send protocol with the number you wrote against, and check protocol in the reply. A daemon on a higher one may have changed something you use.
  • To tell whether the daemon has a command or flag, send it. A daemon without one answers ERR_UNKNOWN_COMMAND or ERR_INVALID_INPUT.
  • A daemon from before the protocol was numbered refuses the protocol field as unknown, and its replies carry none. Send {"action":"ping"} first to find out which you have.

A Go program can import github.com/y3owk1n/neru/client instead of writing any of this. It finds the endpoint the way the CLI does, sends protocol 1, and returns typed replies for status, describe, the queries and watch. Its API follows the rule above and breaks only at a major Neru release. See the package documentation.

Neru publishes the shapes on this page as a JSON Schema, generated from the types the daemon encodes:

https://raw.githubusercontent.com/y3owk1n/neru/main/schemas/ipc.schema.json

Replace main with a release tag to read that release’s copy. Releases from before the schema have no copy of it. neru schema ipc prints the installed build’s copy without fetching anything. Each shape is a definition to $ref, such as #/definitions/status:

DefinitionShape
request, responseA request and a reply
statusThe data of status, and the status of a watch snapshot
query_displays, query_cursor, query_window, query_app, query_hintsThe data of each query
action_snapThe data of action running snap
toggle_scroll_invert, toggle_screen_share, toggle_cursor_follow_selectionThe data of each toggle
watch_lineOne line of a watch after its reply
describeThe data of describe
configThe data of config with no args, a reference to config.schema.json

A key the schema marks required is always present, and may be null where the schema allows it. A reply may carry keys the schema does not list, as Compatibility allows, and a request may not.

args are the words a user types after the command, one string each, with flags written as --flag=value or as two entries.

The daemon parses mode flags exactly as the CLI does. It refuses an unknown flag, a flag the mode does not accept, an unusable value, or an unmet dependency such as --on-exit without --action with ERR_INVALID_INPUT. It ignores a leading repeat of the mode’s own name in args.

The last column says whether the command answers while Neru is stopped by neru stop. A command marked no gets ERR_NOT_RUNNING until start.

CommandargsdataAnswers while stopped
hints, grid, recursive_grid, bisect, scroll, monitor_select, vimThe mode’s flags, from the mode flag reference. --targets carries its JSON as one entry, as --targets={"hints":[…]}. OK means the daemon accepted the activation, as What a mode command answers explains. A mode the config disables gets ERR_MODE_DISABLED.noneno
idlenonenoneyes
modeThe declared mode’s name, then optionally --toggle. OK means the same as for the modes above.noneno
actionAn action name, then its flags, as after neru action.action_snap for snap, none otherwiseno
runOne entry per step, as neru run takes them. --stop-on-error as an entry of its own sets the policy. The daemon drops blank entries, and a request with no steps left gets ERR_INVALID_INPUT. The daemon refuses a sequence nested more than five levels deep with ERR_INVALID_INPUT before any of its steps run, and the sequence that started it reports that as one failed step.noneno
macroThe macro’s name, then its arguments.noneno
pingnonenoneyes
start, stopnone. start while running gets ERR_ALREADY_RUNNING, and stop while stopped gets ERR_NOT_RUNNING.noneyes
statusnoneThe object neru status --json prints.yes
healthnoneThe checks neru doctor reports, as version, config, mode, capabilities, profile and components. A failed check makes the reply ERR_ACTION_FAILED, and the reply still carries data.yes
configNone, or set <key> <value>, reset <key> or reload. set and reset take --no-reload last.With no args, the running configuration under the key names config.toml uses, which neru config dump prints.yes
config-set<key> <value>, then optionally --no-reload.noneyes
reloadnonenoneyes
toggle-scroll-invertOptionally --state on|off|toggle, as in Runtime toggles.{"inverted": bool}yes
toggle-screen-shareOptionally --state on|off|toggle, as in Runtime toggles. ERR_NOT_SUPPORTED on Linux, where nothing can hide the overlay.{"hidden": bool}yes
toggle-cursor-follow-selectionOptionally --state on|off|toggle, as in Runtime toggles.{"following": bool}yes, but stop exits the mode, so it gets ERR_INVALID_INPUT
query-displays, query-cursor, query-window, query-appSee Querying.See Querying.yes
query-hintsSee Querying.See Querying.no
describenoneThe object neru describe --json prints.yes
watchNone, or --event=<name>[,<name>...], repeatable, to send only those events.A stream.yes

A bad key or value for config set, or for config-set, gets ERR_INVALID_INPUT, with or without --no-reload. A change that cannot be saved gets ERR_ACTION_FAILED. config reset with an unknown key gets ERR_INVALID_INPUT.

query-displays, query-cursor, query-window, query-app and query-hints return in data the objects neru query prints with --json. The one exception is query-window when no window has focus. It answers OK with no data key at all, where neru query window --json prints null.

Only query-hints takes args: --role, --text, --strategy, --capture-scope, --label-direction and --split-word, written as a user types them. It refuses anything else with ERR_INVALID_INPUT.

{ "action": "query-hints", "args": ["--role=button", "--strategy=vision"] }

watch keeps the connection open. The daemon sends one response, then one JSON object per line until it exits or you close the connection. The lines are the ones neru watch prints.

{ "action": "watch" }
{ "action": "watch", "args": ["--event=mode_enter,mode_exit"] }

With --event, the daemon sends only the events named, and every snapshot. An unknown event name refuses the stream with ERR_INVALID_INPUT.

Send nothing after the request. To end a watch, close your end. Shutting down only your write side ends it too. The daemon disconnects a reader once a line has waited 5 seconds to send, and a 17th open watch gets ERR_BUSY.

CodeMeaning
OKCommand succeeded
ERR_UNKNOWN_COMMANDNo such command
ERR_INVALID_INPUTMalformed arguments, flag values or request fields
ERR_NOT_RUNNINGNeru is paused via neru stop
ERR_ALREADY_RUNNINGstart while Neru is already running
ERR_MODE_DISABLEDThe requested mode is disabled in the configuration
ERR_ACTION_FAILEDThe action was dispatched but did not complete
ERR_CHAIN_BAILAn action chain aborted, for example --bail
ERR_NOT_SUPPORTEDNot implemented on this platform
ERR_VERSION_MISMATCHThe client needs a newer protocol, or the neru binary and the daemon are different builds. Restart the daemon after an upgrade.
ERR_BUSYToo many watches are open

A connection error rather than a response code means no daemon is running.