Skip to content
Nightly docs track main and may describe features that are not released yet. Docs for the current release (v1.63.0) are here.

Scripting

Every hotkey step is also a shell command, so anything a binding does, a script, a launcher or another hotkey daemon can do too. Each neru command prints its reply, writes errors to stderr, and exits non-zero on failure. Commands are in the CLI reference, and the neru status --json fields under neru status.

Terminal window
if [ "$(neru status --json | jq -r .enabled)" = true ]; then neru stop; else neru start; fi
Terminal window
neru status &>/dev/null && echo "Running" || echo "Not running"

neru doctor --json prints every check as one object, and the reference says what each key means. This notifies when the check fails:

Terminal window
neru doctor --json | jq -e .healthy >/dev/null || notify-send "Neru is unhealthy"

neru services status --json reports whether the login service is installed and running, and neru roles --json how your roles resolve on this machine.

~/.config/skhd/skhdrc
ctrl - f : neru hints
ctrl - g : neru grid
ctrl - r : neru hints --action right_click

Use neru run instead of chaining neru calls with &&. It sends the whole sequence in one request, under hotkey binding rules.

To leave every global hotkey to the other daemon, see Recipes.

Steps under [hooks] run when something happens, such as a mode opening or the focused app changing. Their exec steps see the event as environment variables.

~/.config/neru/config.toml
[hooks]
on_mode_enter = "exec sketchybar --trigger neru_mode MODE=\"$NERU_MODE\""
on_mode_exit = "exec [ \"$NERU_REASON\" = switched ] || sketchybar --trigger neru_mode MODE=idle"

The exit hook skips the trigger when NERU_REASON is switched, because the next mode’s enter hook follows. Neru starts the two hooks at the same time, so an idle trigger sent on a switch can reach sketchybar after the new mode and leave the bar showing idle.

Hooks also fire on each selection a mode makes, sticky modifiers, cursor slots, display changes, and the daemon starting and quitting. The reference lists every event and what each one passes.

A binding’s --on-exit steps see the selection in NERU_X and NERU_Y, so a script can use the point you pick without a hook running for every binding. This copies it to the clipboard on macOS:

~/.config/neru/config.toml
[hotkeys]
"Primary+Shift+P" = "hints --action move_mouse --on-exit 'exec printf \"%s,%s\" \"$NERU_X\" \"$NERU_Y\" | pbcopy'"

A hook starts a process per event. A bar that runs its own long-lived command, such as Waybar’s exec or an Eww deflisten, can read neru watch instead. The script below prints the current mode, then a new line each time the mode changes. --event leaves out every other event, and a mode_exit with reason switched prints nothing, because the next mode’s mode_enter follows.

Terminal window
neru watch --event mode_enter,mode_exit | jq --unbuffered -r '
if .event == "snapshot" then .status.mode
elif .event == "mode_enter" then .mode
elif .reason != "switched" then "idle"
else empty end'

Save it as an executable script, for example ~/.local/bin/neru-mode, and point the bar at it:

; eww.yuck
(deflisten neru_mode "neru-mode")

neru query reports the displays and the cursor in the coordinates neru action move_mouse takes, so a script can pass them straight back. This prints the name of the display under the cursor:

Terminal window
neru query cursor --json | jq -r .display

neru query hints reports the label hints mode would draw on each element. To select one, open hints mode with the same flags and feed it the label. This script clicks the first element its flags select:

#!/bin/sh
# neru-click: click the first element the given hints flags select
label=$(neru query hints "$@" --json | jq -r '.hints[0].label // empty')
[ -n "$label" ] || { echo "neru-click: no match" >&2; exit 1; }
neru hints "$@" --action left_click
neru action feed --mode $(echo "$label" | fold -w1)

Save it as an executable script, for example ~/.local/bin/neru-click, and run neru-click --text Save. It passes the same flags to both commands, because Neru assigns labels afresh on every scan and a label holds only for the same flags. fold -w1 splits a label such as AS into one key per argument.

When an app hides its controls from every strategy, a tool that knows where they are can pass them to hints mode. --targets takes the JSON neru query hints --json prints, so you can filter a query and feed it back. Any tool that writes the same shape works too:

Terminal window
some-tool --emit-targets | neru hints --targets - --action left_click

The details are under Supplying your own targets.

To skip the neru binary, send JSON over the socket, or import the Go client github.com/y3owk1n/neru/client. See Build on Neru for programs built this way, and IPC protocol for the protocol and its schemas.