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.
Endpoint
Section titled “Endpoint”The endpoint is private to your user:
| Platform | Endpoint |
|---|---|
| macOS and Linux | $XDG_RUNTIME_DIR/neru/neru.sock, else $TMPDIR/neru-<uid>/neru.sock |
| Windows | The 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.
Request
Section titled “Request”{ "action": "hints", "args": ["--action=left_click"], "protocol": 1 }| Field | Type | Description |
|---|---|---|
action | string | Required. The command. |
args | string[] | The command’s arguments, written as a user types them after neru. |
protocol | int | The protocol the client needs. The daemon refuses a higher number than its own with ERR_VERSION_MISMATCH. |
version | string | The 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.
Response
Section titled “Response”{ "protocol": 1, "success": true, "message": "OK", "code": "OK" }| Field | Type | Description |
|---|---|---|
protocol | int | The protocol the daemon speaks. |
success | bool | Whether the command did what it was asked. |
code | string | One of the response codes. |
message | string | A sentence for people. Branch on code, never on this. |
data | any | The command’s payload, when it has one, such as the status object. |
version | string | The daemon’s build version. |
Compatibility
Section titled “Compatibility”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
messagetext. - The
versionstring. - The contents of
capabilities,profileandcomponents. - The wording of the prose fields in
describe:usage,description,valueandnote. - 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
protocolwith the number you wrote against, and checkprotocolin 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_COMMANDorERR_INVALID_INPUT. - A daemon from before the protocol was numbered refuses the
protocolfield 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.
Schemas
Section titled “Schemas”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.jsonReplace 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:
| Definition | Shape |
|---|---|
request, response | A request and a reply |
status | The data of status, and the status of a watch snapshot |
query_displays, query_cursor, query_window, query_app, query_hints | The data of each query |
action_snap | The data of action running snap |
toggle_scroll_invert, toggle_screen_share, toggle_cursor_follow_selection | The data of each toggle |
watch_line | One line of a watch after its reply |
describe | The data of describe |
config | The 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.
Commands
Section titled “Commands”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.
| Command | args | data | Answers while stopped |
|---|---|---|---|
hints, grid, recursive_grid, bisect, scroll, monitor_select, vim | The 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. | none | no |
idle | none | none | yes |
mode | The declared mode’s name, then optionally --toggle. OK means the same as for the modes above. | none | no |
action | An action name, then its flags, as after neru action. | action_snap for snap, none otherwise | no |
run | One 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. | none | no |
macro | The macro’s name, then its arguments. | none | no |
ping | none | none | yes |
start, stop | none. start while running gets ERR_ALREADY_RUNNING, and stop while stopped gets ERR_NOT_RUNNING. | none | yes |
status | none | The object neru status --json prints. | yes |
health | none | The 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 |
config | None, 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. | none | yes |
reload | none | none | yes |
toggle-scroll-invert | Optionally --state on|off|toggle, as in Runtime toggles. | {"inverted": bool} | yes |
toggle-screen-share | Optionally --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-selection | Optionally --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-app | See Querying. | See Querying. | yes |
query-hints | See Querying. | See Querying. | no |
describe | none | The object neru describe --json prints. | yes |
watch | None, 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.
Querying
Section titled “Querying”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"] }Streaming
Section titled “Streaming”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.
Response codes
Section titled “Response codes”| Code | Meaning |
|---|---|
OK | Command succeeded |
ERR_UNKNOWN_COMMAND | No such command |
ERR_INVALID_INPUT | Malformed arguments, flag values or request fields |
ERR_NOT_RUNNING | Neru is paused via neru stop |
ERR_ALREADY_RUNNING | start while Neru is already running |
ERR_MODE_DISABLED | The requested mode is disabled in the configuration |
ERR_ACTION_FAILED | The action was dispatched but did not complete |
ERR_CHAIN_BAIL | An action chain aborted, for example --bail |
ERR_NOT_SUPPORTED | Not implemented on this platform |
ERR_VERSION_MISMATCH | The client needs a newer protocol, or the neru binary and the daemon are different builds. Restart the daemon after an upgrade. |
ERR_BUSY | Too many watches are open |
A connection error rather than a response code means no daemon is running.