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.

Configuration reference

Every option in config.toml, with its type and default. Set only what you want to change, since anything left out keeps its default.

This page lists facts. To create the file and apply changes, see Configuring Neru. For how bindings combine, see How bindings work. For ready-made configs, see Recipes.

Neru publishes a JSON Schema for config.toml. An editor that reads it completes keys and flags mistakes while you type. Without an editor, neru config validate reports a misspelled key as a warning, and Neru refuses a wrong type or a malformed color when it loads the file. Taplo, and the Even Better TOML extension built on it, find the schema through a comment on the first line of the file:

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

neru config init writes that line for you, naming the schema of the version you run. To pin an existing file to your version, replace main with its release tag. Releases from before the schema have no copy of it, so an editor reports their URL as a schema it cannot load.

Neru checks the file each time it loads it, at launch and on every reload. Each problem it finds is either refused or warned about.

  • Refused. A TOML syntax error, a wrong type, a malformed color, a value out of range, or a conflict this page marks as refused. Neru drops the whole file, not just the bad line. At launch it prints the error, shows an alert where the platform has one, and exits. A reload keeps the config already running, and on_config_reload sees NERU_OK=false.
  • Warned. An unknown key, an option that does nothing on this platform, a deprecated key, or a setting that loads but cannot take effect. The file loads anyway.

neru config validate prints both without touching the daemon. The daemon logs each warning when it loads the file. Why a problem lands in one tier or the other is in ADR 0002.

The syntax and defaults of every hotkey table. When each table applies, and which one answers a key, is in How bindings work.

[hotkeys]
"Primary+Shift+Space" = "hints"
"Primary+Shift+W" = ["action save_cursor_pos", "hints --action left_click"]

The key is a chord, "Mod1+Mod2+Key". The value is one step or an array of steps.

Defaults. macOS and Windows bind Primary+Shift+Space (hints), Primary+Shift+G (grid), Primary+Shift+C (recursive grid), Primary+Shift+B (bisect) and Primary+Shift+S (scroll). Linux binds none, see Getting started.

ModifierAliases
CmdCommand, Super, Meta
CtrlControl
AltOption
Shift
PrimarySet per platform by general.primary_modifier, Cmd on macOS and Ctrl on Linux/Windows by default
CategoryKeys
Lettersa to z, A to Z
Numbers0 to 9
Symbols`, -, =, [, ], \, ;, ', ,, ., /
NamedSpace, Return, Enter, Escape, Tab, Delete, Backspace
NavigationUp, Down, Left, Right, Home, End, PageUp, PageDown, Insert (Linux and Windows only)
FunctionF1 to F24 (F21 to F24 on Linux and Windows only)
  • Shift with a symbol is written as the character Shift produces. On Linux, Shift plus the ; key is "Shift+:", not "Shift+;". Letters are unaffected.
  • Delete and Backspace both name the key that erases to the left. The forward-delete key has no hotkey name.
  • The full key list with platform behavior is under neru action feed.
ConfigResult
Section absentAll defaults used
Section present, emptyAll hotkeys disabled
Section has entriesMerged on top of defaults

Use __disabled__ to remove one default:

[hotkeys]
"Primary+Shift+S" = "__disabled__" # removes default scroll binding
"Ctrl+Space" = "hints" # moves hints off its default chord

An entry whose only step opens a built-in mode moves that mode’s launcher. Neru drops every default chord that opens the same mode, so in the example Primary+Shift+Space stops opening hints. Bind the default chord again to keep both. This holds with flags too, as in "Ctrl+Space" = "hints --action left_click".

Disabling a mode (enabled = false) also removes its default launcher hotkey, and neru <mode> then fails with ERR_MODE_DISABLED.

[<mode>.hotkeys] follows the same merging rules, and also accepts two-letter sequences such as gg. Neru refuses the file when:

  • A single key shadows a sequence that starts with it, such as "g" in [scroll.hotkeys] beside the default "gg". The single key always matches first, so the sequence could never fire. Disable one of them.
  • Two keys you write name the same chord once aliases are resolved, such as "Ctrl+Space" and "Control+Space". [hotkeys] refuses this too. A key that matches a default this way replaces the default.

Every built-in mode except monitor_select and vim ships these, plus the defaults listed in its own section:

"Escape" = "idle"
"Shift+L" = "action left_click"
"Shift+R" = "action right_click"
"Shift+M" = "action middle_click"
"Shift+I" = "action left_click --state down"
"Shift+U" = "action left_click --state up"
"Up" = "action move_mouse_relative --dx=0 --dy=-10"
"Down" = "action move_mouse_relative --dx=0 --dy=10"
"Left" = "action move_mouse_relative --dx=-10 --dy=0"
"Right" = "action move_mouse_relative --dx=10 --dy=0"

[[<mode>.app_configs]] overrides [<mode>.hotkeys] for hints, grid, recursive_grid, bisect, vim, scroll and declared modes ([[modes.<name>.app_configs]]), under the same merging rules.

[[hints.app_configs]]
bundle_id = "com.brave.Browser"
hotkeys = { "Return" = "action left_click", "Shift+L" = "__disabled__" }

An entry applies while its app is focused. Its hotkeys merge over the mode’s table, and each other field it sets replaces the mode’s value. A field left out, or a string left empty, keeps the mode’s value. The bool fields have a third state, unset, so an entry can write ignore_clickable_check = false to turn off for one app what [hints] turns on. Neru refuses two entries in one mode with the same bundle_id, compared regardless of case. It also refuses a field that belongs to another mode, such as scroll_step under [[hints.app_configs]] or additional_clickable_roles under [[grid.app_configs]].

A root-level [[app_configs]] entry overrides [hotkeys] for one app:

[[app_configs]]
bundle_id = "com.apple.Terminal"
hotkeys = { "Cmd+Space" = "hints", "Cmd+Shift+Space" = "__disabled__" }

bundle_id selects the app for [[app_configs]], every [[<mode>.app_configs]] and excluded_apps. To find it on any platform, run sleep 3; neru query app and switch to the app before the three seconds are up. It prints the exact string Neru matches. What that string is depends on the platform:

PlatformIdentity Neru matchesHow to find it
macOSBundle ID, reverse-DNS, such as com.apple.Safariosascript -e 'id of app "Safari"'
Linux · X11Window WM_CLASS, the class fieldxprop WM_CLASS, then click the window
Linux · WaylandToplevel app_idswaymsg -t get_tree (Sway), hyprctl activewindow (Hyprland), niri msg windows (niri), or your compositor’s window inspector
WindowsFull path of the focused window’s executable, such as C:\Program Files\Google\Chrome\Application\chrome.exeTask Manager, Details tab, right-click the process, Open file location, or (Get-Process chrome).Path in PowerShell

Matching is case-insensitive and exact, with no globbing or partial matches.

  • Linux identity strings vary by toolkit. Examples are Google-chrome, code and org.kde.konsole. Confirm with the commands above.
  • On Windows, write the path as a TOML literal string ('C:\...') or double every backslash. A copy installed elsewhere, such as under %LOCALAPPDATA%, needs its own entry. Microsoft Store apps all share the identity ApplicationFrameHost.exe and cannot be told apart.
  • On GNOME under Wayland, no entry matches until the Neru GNOME Shell extension loads after your first re-login. See GNOME (Wayland).

Named action sequences, invoked from any binding with macro <name> [args...]. A macro is written, not recorded.

[macros]
click_and_exit = ["action left_click --bail-on-error", "idle"]
say = ["exec say \"$1\""]
[hints.hotkeys]
"Enter" = "macro click_and_exit"
"Shift+S" = "macro say hello"

A worked example with arguments is in Recipes.

  • Names use letters, digits, _ and -, and start with a letter.
  • Arguments are positional: $1, $2, and so on, with $$ for a literal dollar sign. Substitution is textual and happens before the step is split, so quote a placeholder that may hold spaces, as in exec say "$1".
  • Arity is checked at load wherever an action can be written, including hooks and nested run or --on-exit steps. An unknown name or wrong argument count fails neru config validate.
  • A placeholder cannot be the command word. "$1 --action left_click" is rejected at load.
  • A macro runs as a nested sequence, so it can call other macros, and its failure counts as one failed step to the caller.
  • A mode’s --action does not take a macro. Use --on-exit.
  • Run a macro from outside with neru macro <name> [args...].

Modes you declare yourself. A declared mode is a name, an indicator label and a hotkey table. While it is open Neru captures the keyboard and answers every key from that table, so it works as a layer of bare-letter bindings.

[modes.window]
indicator = "Window"
[modes.window.hotkeys]
"h" = "exec yabai -m window --focus west"
"f" = ["exec yabai -m window --toggle zoom-fullscreen", "idle"]
"s" = "scroll"
[hotkeys]
"Primary+Shift+W" = "mode window"
  • Entering. Use the step mode <name> from any binding, macro or run, or neru mode <name>. It accepts only --toggle. A step naming an undeclared mode is refused at load.
  • Leaving. Escape is bound to idle by default ("Escape" = "__disabled__" removes it). Any binding ending in idle or another mode also leaves. Unbound Ctrl/Alt/Cmd chords fall back to [hotkeys], see Which binding wins, and unbound bare keys are swallowed.
OptionTypeDefaultDescription
indicatorstring""Mode indicator text while the mode is open, empty hides it
hotkeysmap{ "Escape" = "idle" }The mode’s hotkeys, merged over the default

The name is the table key: letters, digits, _ and -, starting with a letter. Neru refuses the built-in mode names (hints, grid, recursive_grid, bisect, scroll, monitor_select, vim, idle) and mode. The indicator style comes from [mode_indicator.ui].

[[modes.<name>.app_configs]] takes bundle_id and hotkeys.

Steps Neru runs when something happens, written like any binding and checked at load the same way.

[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"
on_config_reload = "exec [ \"$NERU_OK\" = true ] || say 'Neru config did not load'"
OptionTypeDefaultRuns when
on_mode_enterstring/arraynoneA mode opens
on_mode_exitstring/arraynoneA mode closes, including on the way into another one
on_selectstring/arraynoneA step you take moves a mode’s target, such as a hint label, a grid cell or a recursive grid level, or a snap moves the cursor
on_app_focusstring/arraynoneAnother application comes to the front
on_enablestring/arraynoneNeru resumes, such as on neru start
on_disablestring/arraynoneNeru pauses, such as on neru stop
on_config_reloadstring/arraynoneA config reload finishes, whether or not the new file loaded
on_mission_control_activatedstring/arraynoneMission Control opens. macOS only, needs hints.detect_mission_control
on_mission_control_deactivatedstring/arraynoneMission Control closes. macOS only, needs hints.detect_mission_control
on_scroll_invertstring/arraynoneScroll inversion switches on or off
on_screen_share_hidestring/arraynonetoggle-screen-share switches on or off. macOS and Windows only, since nothing hides the overlay on Linux
on_cursor_savestring/arraynonesave_cursor_pos saves a position
on_cursor_restorestring/arraynonerestore_cursor_pos takes a saved position, which empties its slot
on_sticky_modifiersstring/arraynoneA sticky modifier is armed or released. Needs sticky_modifiers.enabled
on_monitor_movestring/arraynonemove_monitor or monitor_select moves the cursor to another display
on_screen_changestring/arraynoneThe displays change, such as on a dock, an undock or a wake
on_readystring/arraynoneThe daemon has started and takes hotkeys
on_quitstring/arraynoneThe daemon starts to shut down. Runs exec steps only

A reload takes effect from the next event.

on_select runs once per step, so zooming a recursive grid three levels runs it three times, and a --repeat mode runs it for each selection. A click from a mode key such as Shift+L is an action, not a step that moves the target, so it does not run on_select. A snap that moves the cursor runs it once, with NERU_ACTION set to snap, in idle as well as in a mode.

A hook runs for every binding. To run steps after one binding’s selection only, give that binding --on-exit. How the three compare:

  • on_select runs for every binding, once per step that moves the target.
  • --on-exit runs for one binding, once, after its action. It never runs on a cancel. Its exec steps see the variables on_select sets, listed below.
  • on_mode_exit runs on every close, a cancel included.

--on-exit and on_select both start after the selection, in no set order, so do not give both a step that opens a mode.

hints.on_mission_control_activated and hints.on_mission_control_deactivated are deprecated and are removed in v2. Move their steps to the two keys here, which take the same values. Until then the [hints] keys still run, alongside these. Both pairs need hints.detect_mission_control = true, and act differently when it is off:

  • The deprecated [hints] keys refuse the file.
  • The [hooks] keys load, and neru config validate warns that they never run.

With it on, neru config validate warns about each deprecated key set.

exec steps get the event as environment variables. Each is set only for the events that carry it.

VariableSet forValue
NERU_EVENTevery hookThe event, such as mode_enter
NERU_MODEon_mode_enter, on_mode_exit, on_selectThe mode, named as neru status names it
NERU_REASONon_mode_exitcompleted after a selection, switched when another mode opens in its place, else canceled
NERU_ACTIONon_mode_exit, on_selectThe action the selection ran, such as left_click, or left_click,left_click for a chain, or snap for a snap. on_mode_exit sees it only when NERU_REASON is completed. Unset when it ran none, such as for a binding with no --action
NERU_BUNDLE_IDon_app_focusThe application, as bundle_id names it
NERU_OKon_config_reloadtrue or false
NERU_ONon_scroll_invert, on_screen_share_hidetrue when switched on, else false
NERU_SLOTon_cursor_save, on_cursor_restoreThe cursor slot, default when none was named
NERU_Xon_select, on_cursor_saveThe x of the position saved, or of the point selected
NERU_Yon_select, on_cursor_saveThe y of the position saved, or of the point selected
NERU_MODIFIERSon_sticky_modifiersThe set held now, such as cmd,shift, in the spelling --modifier takes. Empty when none is
NERU_MONITORon_monitor_moveThe display, as move_monitor --name takes it

A binding’s --on-exit steps get the same variables as the on_select hook for that selection, so NERU_EVENT is select. They are not a hook, so they do not run while Neru is stopped.

Use them in the command as shell variables, in double quotes, such as "$NERU_MODE". Neru passes them to the shell as environment variables and never writes their values into the command text. That matters for NERU_BUNDLE_ID, which the application chooses for itself. On X11 any program can set it, and a crafted value such as x; rm -rf ~ stays plain text instead of running as a command.

  • A slow hook never delays a mode. It runs after the change it reports, apart from key handling.
  • A busy hook misses events. An event raised while its own hook is still running does not start that hook again, so a hook cannot keep another program in step with every change. Use it to act on an event. The same rule stops on_mode_enter = "grid" from looping, so it enters grid once.
  • Each hook runs once at a time, and hooks for different events can run together.
  • Two hooks that keep triggering each other loop until the config changes, and Neru does not catch it. An example is on_mode_exit = "hints" with on_mode_enter = "idle".
  • While Neru is stopped, the only hooks that run are on_enable, on_disable, on_ready, on_quit, and on_mode_exit for the mode the pause closed. Their exec steps run even though Neru is stopped. Neru refuses their other steps, such as opening a mode, until it starts.
  • on_quit runs before anything shuts down. Neru runs only its exec steps and skips the rest, such as a step that opens a mode. neru config validate warns about each step it will skip. Shutdown waits at most one second for the hook, then continues without it.

Behavior not tied to one mode.

[general]
excluded_apps = ["com.apple.Terminal"]
passthrough_unbounded_keys = true
OptionTypeDefaultDescription
excluded_appsarray[]Apps where Neru won’t activate, by app identity
kb_layout_to_useper platform""Keyboard layout keys are named in, as the platform names it (auto if empty). See below
hide_overlay_in_screen_shareboolfalseHide overlay in screen sharing apps. On Windows it also leaves the overlay out of screenshots and recordings
passthrough_unbounded_keysboolfalseLet unbound Cmd/Ctrl/Alt shortcuts pass through
should_exit_after_passthroughboolfalseExit mode after a passthrough shortcut
passthrough_unbounded_keys_blacklistarray[]Shortcuts to keep consumed when passthrough is on
shellper platformsee belowThe shell and arguments an exec step runs, with the command string appended last. See below
primary_modifierper platformsee belowThe modifier Primary stands for. See below
exec_shellstringnoneDeprecated, removed in v2. Use shell. When set, replaces the shell on every platform
exec_shell_argsarraynoneDeprecated, removed in v2. Use shell. When set, replaces the arguments on every platform

passthrough_unbounded_keys and should_exit_after_passthrough work on macOS, Windows and Wayland with the evdev keyboard proxy. X11 cannot pass a grabbed chord through.

kb_layout_to_use, shell and primary_modifier take their own value on each platform, so one config file can serve every machine. Write a table keyed by darwin, linux and windows:

[general]
primary_modifier = { darwin = "Cmd", linux = "Super", windows = "Ctrl" }
kb_layout_to_use = { darwin = "com.apple.keylayout.Dvorak", linux = "English (Dvorak)" }
[general.shell]
darwin = ["/bin/zsh", "-lc"]
linux = ["/bin/bash", "-lc"]

Or write one value, which every platform takes, such as shell = ["/bin/zsh", "-lc"].

A platform the table leaves out keeps its default. Neru refuses a key that names no platform, such as macos. Platforms other than macOS and Windows read linux. To change one entry at runtime, name it, as in neru config set general.shell.linux '["/bin/zsh", "-c"]'. Naming the option alone, as in neru config set general.kb_layout_to_use 00010409, gives every platform that value.

shell is the command line an exec step runs, with the step’s command string appended as the last argument. Every entry needs at least one argument, and the entry for the platform Neru runs on has to start with an absolute path. So one value such as shell = ["/bin/zsh", "-lc"] loads on macOS and Linux, and Windows refuses it. The default is ["/bin/bash", "-lc"] on macOS and Linux and ['C:\Windows\System32\cmd.exe', "/c"] on Windows. If Windows is installed on another drive, set the windows entry.

Until v2, the deprecated exec_shell and exec_shell_args still work. When set, exec_shell replaces the shell and exec_shell_args replaces the arguments, on every platform. neru config validate warns about each one that is set.

primary_modifier names the modifier a Primary hotkey uses. Each entry is one of Cmd, Ctrl or Alt, or an alias of one from the modifier table. The defaults are Cmd on macOS and Ctrl on Linux and Windows. A reload or neru config set applies a change at once, to every Primary hotkey in every table.

kb_layout_to_use decides which physical key a binding answers. Empty picks a layout with Latin letters, so bindings stay put while you type in another language. To force one, set the entry for that platform in the name the platform uses:

PlatformValueExample
macOSInput source IDcom.apple.keylayout.Dvorak
LinuxXKB layout name, matched regardless of caseEnglish (Dvorak)
WindowsKeyboard layout identifier00010409

The keyboard_layouts row of neru doctor lists the layouts Neru sees, in this option’s form, and the one in use. An unmatched value is reported there and in the log, and Neru keeps its automatic choice.

Base colors from which all component defaults are derived, set in [theme.light] and [theme.dark]. Use solid #RRGGBB or #RGB (no alpha). An explicit component color overrides the derived one.

[theme.light]
accent = "#465FBC"
[theme.dark]
accent = "#6E82D6"
KeyRoleLight defaultDark default
surfaceTranslucent fills, badges, indicator backgrounds#EEF2FF#0A1338
accentBorders, lines, primary chrome#465FBC#6E82D6
accent_altActive/emphasis states, highlights, virtual pointer#0B2377#8FA2F0
on_accent_altForeground text/icon on accent_alt surfaces#F8FAFF#081022
textForeground text on surface backgrounds#17327A#E8EEFF

Every color option takes hex with optional alpha. The alpha byte is round(opacity * 255), so 95% is F2 and 70% is B3. A color is a string, or a table with light and dark keys such as { light = "#AAFF0000", dark = "#AA00FF00" }. A color you leave out is derived from [theme] and follows the system appearance.

FormatExampleAlphaNotes
#AARRGGBB#FF000000YesRecommended format
#RRGGBB#FF0000NoFully opaque
#RGB#F00NoShorthand

Every font_family option takes a family name, or one of the generic aliases sans, serif and mono, which resolve to each platform’s own faces. Empty means sans. On Linux and Windows, a family the system cannot find falls back to DejaVu Sans or Segoe UI.

Labels clickable elements. The default axtree strategy reads the platform accessibility tree. Three screen-capture strategies cover apps with a thin tree. Each scans the focused window by default and adds the system surfaces the include_* options ask for.

  • vision: one OCR pass per activation, so hint search (--search) and --split-word work. What it finds on each platform is in Platform support.
  • contour: edge analysis from wl-kbptr, a few milliseconds with no dependency. Its hints carry no text, so search and word splitting do not apply. Tune it under [hints.contour].
  • segment: splits the screen image into controls, pictures and words, in a few milliseconds with no dependency. One hint goes on each button, field or chip, and it finds controls drawn over a photo or a wallpaper too. By default each word of text gets a hint too, so every link is reachable and dense text gets many hints. Like contour, its hints carry no text. Choose what it hints under [hints.segment].

Press / in hints mode to filter hints by text. See the hints search recipe.

[hints]
hint_characters = "asdfghjkl"
strategy = "vision"
[hints.ui]
font_size = 12
OptionTypeDefaultDescription
enabledbooltrueTurn hints mode on or off
strategystring"axtree"Element detection: "axtree", "vision", "contour" or "segment". Overridable per app
capture_scopestring"window"Region vision, contour and segment scan: "window" (the screen if nothing is focused) or "screen". Overridable per app and with neru hints --capture-scope
hint_charactersstring"asdfghjkl"Characters used for labels. Refused if empty, shorter than 2, non-ASCII, or with a repeated character
label_directionstring"normal""normal" or "reverse", see Choosing a label direction. Overridable per app and with neru hints --label-direction
label_alternationstring"none""none" or "halves", see Alternating hands
max_depthint50Deepest accessibility tree level to read, 0 for unlimited
include_menubar_hintsboolfalseShow hints on menubar items
include_dock_hintsboolfalseShow hints on Dock items, and on Mission Control’s windows and desktops while detect_mission_control is on
include_nc_hintsboolfalseShow hints in Notification Center
include_stage_manager_hintsboolfalseShow hints in Stage Manager
include_pip_hintsboolfalseShow hints on Picture in Picture controls
include_screen_capture_hintsboolfalseShow hints on Screen Capture controls
detect_mission_controlboolfalseDetect Mission Control, so hints target its windows and desktops instead of the frontmost window. Refused without include_dock_hints = true
on_mission_control_activatedstring/arraynoneDeprecated, removed in v2. Use hooks.on_mission_control_activated. Refused without detect_mission_control = true
on_mission_control_deactivatedstring/arraynoneDeprecated, removed in v2. Use hooks.on_mission_control_deactivated. Refused without detect_mission_control = true
additional_menubar_hints_targetsarraymacOS-specific defaultsExtra menubar bundle IDs
clickable_rolesarrayshared semantic defaultsRoles that generate hints. See Clickable roles
ignore_clickable_checkboolfalseHint elements of the clickable roles even when the app reports them as disabled. On macOS it also skips the press-action, hidden and hit tests
visible_check_enabledboolfalseEnable visibility hit-test (slower but fewer noisy hints)
select_withtablenoneSteps to run in place of the session’s --action when a label is finished with modifiers held. See Select with modifiers. Overridable per app

label_direction sets how multi-character labels are enumerated once single-character labels run out. With asdf and 5 elements:

DirectionSequenceNotes
normal (default)A S D FA FSKeeps 3 single-char labels, then expands the 4th alphabet slot into 2-char labels.
reverseAA SA DA FA ASFills the 2-char tier uniformly from the first alphabet character.

Use normal for most workflows and for short alphabets, since it needs fewer keystrokes. Use reverse when many hints cluster in one region or you regularly need more than len(hint_characters) hints, since it spreads first characters evenly. Set it per app in the per-app config or per activation with neru hints --label-direction.

label_alternation = "halves" makes each key of a multi-character label come from the opposite hand to the key before it. The first half of hint_characters is one hand and the second half the other, with the extra character in the first half for an odd count. So write each hand’s characters together. The default asdfghjkl splits into asdfg and hjkl, and order within each half still sets which keys are preferred.

Alternation fits fewer labels of each length. With L and R characters in the two halves and N in all, it applies from N+1 hints up to L*R*N, which is 180 for the default. Labels reach three characters after 2*L*R hints (40) instead of after N*N (81). Above L*R*N hints, or with fewer than four characters, labels are the same as with "none". It works with both label directions.

hints.clickable_roles decides which accessibility elements get a hint. Write entries in Neru’s semantic vocabulary, and Neru resolves them to the platform’s AX roles, AT-SPI role names or UI Automation control types.

[hints]
clickable_roles = ["button", "link", "text_field"]

neru roles shows the vocabulary and how each name resolves on this machine. neru roles --explain shows how your config resolves.

SemanticmacOS (ax:)Linux (atspi:)Windows (uia:)
buttonAXButtonpush button, button, toggle buttonButton, SplitButton
menu_buttonAXMenuButtonpush button menu—
popup_buttonAXPopUpButtoncombo boxComboBox
combo_boxAXComboBoxcombo boxComboBox
linkAXLinklinkHyperlink
checkboxAXCheckBoxcheck box, check menu itemCheckBox
radioAXRadioButtonradio button, radio menu itemRadioButton
switchAXSwitch †switch, toggle button—
disclosureAXDisclosureTriangle——
text_fieldAXTextFieldentry ‡, password textEdit
text_areaAXTextAreaentry ‡Edit
search_fieldAXSearchField †entry ‡Edit
sliderAXSlidersliderSlider
stepperAXIncrementorspin buttonSpinner
tabAXTabButton †page tabTabItem
menu_itemAXMenuItemmenu itemMenuItem
menubar_itemAXMenuBarItem——
dock_itemAXDockItem——
cellAXCelltable cellDataItem
rowAXRowtable rowTreeItem
list_itemAXRowlist itemListItem
imageAXImageimage, iconImage
static_textAXStaticTextstatic, label, text ‡Text
headingAXHeadingheading—
color_wellAXColorWellcolor chooser—
toolbar_buttonAXToolbarButton †——

A — means the platform has no equivalent and the entry is ignored there. neru config validate warns about such an entry once your clickable_roles differs from the shipped list, and always for additional_clickable_roles. neru roles --explain and neru doctor always report it.

† A subrole. AppKit reports it in the element’s subrole while the role stays generic. For example, a search field is an AXTextField with subrole AXSearchField. Neru matches names against both role and subrole, so these work as written.

‡ GTK 3 reports its entries and text views as text, which other toolkits use for read-only text. Neru reads a text element as entry when AT-SPI marks it editable, and as text otherwise.

Address any native role directly with its vocabulary prefix:

clickable_roles = [
"button",
"ax:AXDisclosureTriangle", # macOS only
"atspi:page tab list", # Linux only
"uia:Custom", # Windows only
]

Prefixed entries for another platform are ignored, not rejected. Many legacy Win32 and WinForms controls appear only as uia:Pane, uia:Custom or uia:Document and need naming directly. An unprefixed entry must be a semantic role, and an unknown one is a config error:

hints.clickable_roles: unknown role "AXButton": use "button"
OptionTypeDefaultDescription
font_sizeint10Font size in points
font_familystring""Font family. Accepts generic aliases, and empty means the platform’s sans family
border_radiusint-1Corner radius, -1 for automatic
padding_xint-1Horizontal padding, -1 for automatic
padding_yint-1Vertical padding, -1 for automatic
border_widthint1Border width in pixels
placementstring"bottom"Label placement relative to the element: top, center, bottom. top and bottom draw a connector arrow
background_colorcolorderivedBackground color
text_colorcolorderivedText color
matched_text_colorcolorderivedText color for matched characters
border_colorcolorderivedBorder color

Element outlines for dense layouts, in [hints.boundary_highlight].

OptionTypeDefaultDescription
enabledboolfalseDraw element boundaries
border_widthint1Stroke width in pixels
border_radiusint-1Corner radius, -1 for an automatic pill
background_colorcolorderivedElement fill color
border_colorcolorderivedElement stroke color

[hints.search_input_ui] also takes the hints UI options except placement and matched_text_color.

OptionTypeDefaultDescription
positionstring"bottom_center"Anchor: top_left, top_center, top_right, center, bottom_left, bottom_center, bottom_right
x_offsetint0Horizontal offset from anchor
y_offsetint24Vertical offset from anchor
widthint320Width in pixels

[hints.vision] is read only when the global or per-app strategy is "vision". Turning off both detect_text and detect_rectangles refuses the file, whatever the strategy. The rectangle and confidence options do nothing on some platforms, see Platform support per word.

OptionTypeDefaultDescription
detect_textbooltrueEnable text detection. With this off, Linux detects nothing
detect_rectanglesbooltrueEnable rectangle detection
request_timeout_msint5000Timeout for one analysis request (one OCR pass on Linux), in ms
minimum_confidencefloat0.0Minimum confidence (0.0 to 1.0) for keeping an observation
merge_iou_thresholdfloat0.5Intersection-over-Union overlap at which boxes merge
rectangle_max_candidatesint100Maximum rectangle candidates to evaluate
rectangle_min_sizefloat0.01Minimum rectangle size as a fraction of the captured region’s shorter side (0.01 is 1%)
rectangle_min_aspectfloat0.3Minimum rectangle aspect ratio (width/height)
rectangle_max_aspectfloat10.0Maximum rectangle aspect ratio (width/height)
button_min_confidencefloat0.3Minimum confidence for classifying a rectangle as a button
button_min_aspectfloat0.8Minimum aspect ratio for buttons
button_max_aspectfloat8.0Maximum aspect ratio for buttons
button_icon_max_sizeint48Maximum width/height in pixels for square buttons or icons
link_min_aspectfloat5.0Minimum aspect ratio for text links
link_max_heightint40Maximum height in pixels for text links
link_min_widthint50Minimum width in pixels for text links
image_min_sizeint48Minimum width/height in pixels for images
checkbox_max_sizeint32Maximum width/height in pixels for checkboxes
generic_clickable_min_confidencefloat0.5Minimum confidence for generic clickable elements

[hints.contour] works on all three platforms. Defaults are wl-kbptr’s. Sizes are logical pixels (points on Retina). Edge thresholds are Sobel gradient magnitudes on a 0 to 255 grayscale frame, at most 1530. Lower them for faint outlines on low-contrast themes, and widen the target bounds to hint notification cards and toasts.

OptionTypeDefaultDescription
request_timeout_msint2000Time budget for one pass. A pass over budget returns no targets
edge_low_thresholdint70Canny low threshold, which extends an edge. Must be at most the high value
edge_high_thresholdint220Canny high threshold, which starts an edge. Lower finds fainter outlines
min_target_widthfloat7.0Blobs this wide or narrower are noise
min_target_heightfloat3.0Blobs this tall or shorter are noise
max_target_widthfloat650.0Blobs this wide or wider are layout containers
max_target_heightfloat160.0Blobs this tall or taller are layout containers
flat_line_heightfloat6.0Nested strokes no taller than this are dropped (hamburger lines, underlines)
container_heightfloat50.0A blob this tall holding button-sized children is a card and is dropped for them
same_center_slackfloat8.0A nested blob whose center is this close to its parent’s duplicates the parent
square_icon_sizefloat40.0A roughly square parent smaller than this keeps its box and drops its inner detail
square_icon_slackfloat5.0How far from square (width minus height) that parent may be

[hints.segment] works on all three platforms.

OptionTypeDefaultDescription
targetsstring"words"What segment hints. "words" puts a hint on every word, so every link is reachable. "phrases" joins words of one color into phrases, for fewer hints on dense text. "controls" hints buttons, fields, icons and pictures, and no text
[hints.segment]
targets = "phrases"
[hints.hotkeys] # plus the shared defaults under Per-mode hotkeys
"/" = "action search_hints"
"Backspace" = "action backspace"
"Tab" = "action cycle_hint"
"Shift+Tab" = "action cycle_hint --backward"

[hints.select_with] lets the key that finishes a label choose what the selection does. Hold a modifier set while typing that key, and the steps for that set run in place of the session’s --action.

[hints.select_with]
ctrl = ["action session_action", "idle"] # the session's action, then exit
alt = "action right_click"
cmd = "action left_click --modifier cmd" # open a link in a new tab
"ctrl+alt" = ["action copy_text", "idle"] # copy the hint's text, then exit
  • Keys are modifier sets: one or more of cmd, ctrl, alt, shift and primary, joined with +, as in "cmd+shift". Aliases such as command, control and option work too. A set matches only when exactly those modifiers are held.
  • Values are steps, written as in a hotkey binding, so actions, macros, exec and mode commands all work. They run after the cursor moves to the hint, so a click step acts on it.
  • action session_action runs the session’s own --action there, with its --modifier. Use it when an entry should do what the session does and then something more, such as exiting a --repeat session in one key.
  • Afterwards the session ends as its --action would have. A --repeat session, or one opened without --action, reopens hints. Any other session exits and runs its binding’s --on-exit. A step that leaves the mode ends it early. Leaving to idle still runs --on-exit, and entering another mode runs nothing. Until the steps finish, Neru ignores labels you type, while bindings such as Escape still work.
  • Hold the modifier for the whole label if you like. Every hint character typed with a set that has an entry goes into the label, and only the key that finishes it decides. A chord whose modifiers have no entry is a key binding as usual.
  • Neru refuses a binding for one of those chords at load. A mapped set plus each hint character is label input, so a binding for any of those chords could never run. Rebind the key or drop the character from hint_characters. With the defaults, shift collides with Shift+L, since l is a hint character. Neru checks every hotkey table in force, global and per-app included.
  • Only a physically held modifier selects an entry. A sticky modifier still means “hold this on the next click”, so a label typed with one runs the session’s action holding it.
  • On Linux a held Shift turns a symbol hint character into its shifted symbol, so use letters with shift.

An empty string or an unset bool keeps the [hints] value. How an entry applies is under Per-app hotkey overrides.

FieldTypeDescription
bundle_idstringApp bundle ID
strategystring"axtree", "vision", "contour" or "segment"
capture_scopestring"window" or "screen"
label_directionstring"normal" or "reverse"
additional_clickable_rolesarrayExtra roles to treat as clickable, same vocabulary as clickable_roles
ignore_clickable_checkboolHint elements of the clickable roles in this app even when it reports them as disabled. On macOS it also skips the press-action, hidden and hit tests
visible_check_enabledboolEnable visibility hit-test for this app
hotkeysmapper-app hotkey overrides
select_withmapEntries that replace select_with ones for the same modifier set while this app is focused. "__disabled__" removes one

Settings for grid mode. How the mode behaves is in neru grid.

[grid]
characters = "asdfghjkl"
capture_scope = "window"
OptionTypeDefaultDescription
enabledbooltrueTurn grid mode on or off
capture_scopestring"screen"Region the grid covers: screen or window (the screen if nothing is focused). --capture-scope overrides it
charactersstring"abcdefghijklmnpqrstuvwxyz"Primary grid labels. Cannot be empty or contain non-ASCII
sublayer_keysstring"abcdefghijklmnpqrstuvwxyz"Subgrid labels, first 9 used (3×3). Empty uses the grid’s label characters. Cannot contain non-ASCII
max_label_lengthint4Maximum coarse-grid label length (2 to 4). A lower limit enlarges the coarse grid to still cover the screen
row_labelsstring""Custom row labels. Empty infers them from characters
col_labelsstring""Custom column labels. Empty infers them from characters
live_match_updatebooltrueHighlight cells as you type
hide_unmatchedbooltrueHide non-matching cells
prewarm_enabledbooltruePre-compute grid on startup
enable_gcboolfalsePeriodic memory cleanup. Needs a daemon restart

Neru checks the label sets at three levels.

  • Refused. An empty characters, non-ASCII in characters or sublayer_keys, or a max_label_length outside 2 to 4.
  • Warned. neru config validate warns, and the file loads, when characters, row_labels or col_labels has a single character, a repeat (case-folded, so aA repeats), whitespace or a control character, or when row_labels or col_labels has non-ASCII. The grid then drops each repeat, and a characters with fewer than two distinct characters falls back to a-z. Short row or column labels cap the grid to the cells they can name. Neru infers an empty row_labels or col_labels from characters, so it reports their faults as characters.
  • Silent. sublayer_keys gets no warning. The grid drops its repeats, so a 9-character set with a repeat leaves one subgrid cell unlabeled.
OptionTypeDefaultDescription
font_sizeint10Largest label size in points. Labels shrink, at one size for the whole grid, to fit small cells, and never hide
font_familystring""Font family. Accepts generic aliases, and empty means the platform’s sans family
border_widthint1Border width in pixels
background_colorcolorderivedCell background
text_colorcolorderivedLabel text
matched_text_colorcolorderivedMatched cell text
matched_background_colorcolorderivedMatched cell background
matched_border_colorcolorderivedMatched cell border
border_colorcolorderivedDefault cell border
[grid.hotkeys] # plus the shared defaults under Per-mode hotkeys
"`" = "toggle-cursor-follow-selection"
"Space" = "action reset"
"Backspace" = "action backspace"
FieldTypeDescription
bundle_idstringApp bundle ID
capture_scopestringscreen or window region for this app
hotkeysmapper-app hotkey overrides

Settings for recursive grid mode. How the mode behaves is in neru recursive_grid.

[recursive_grid]
grid_cols = 2
grid_rows = 2
keys = "uijk" # one key per cell
OptionTypeDefaultDescription
enabledbooltrueTurn the mode on or off
capture_scopestring"screen"Region the first level covers: screen or window (the screen if nothing is focused). --capture-scope overrides it
grid_colsint3Columns, at least 1. Columns times rows must be at least 2
grid_rowsint3Rows, at least 1. Columns times rows must be at least 2
keysstring"rtyfghvbn"Cell selection keys, exactly grid_cols times grid_rows characters
min_size_widthint1Minimum cell width, in apparent pixels (scaled with the display on Windows and X11)
min_size_heightint1Minimum cell height, in apparent pixels (scaled with the display on Windows and X11)
max_depthint10Maximum recursion levels, at least 1
layersarray[]Per-depth layout overrides (see below)

Each entry overrides the grid dimensions and keys at one depth. A depth with no entry uses the top-level grid_cols, grid_rows and keys. An entry must set all three, under the same rules as the top-level ones, or Neru refuses the file.

FieldTypeDefaultDescription
depthint0Depth to override, counted from 0
grid_colsintrequiredColumns at this depth
grid_rowsintrequiredRows at this depth
keysstringrequiredSelection keys, one per cell at this depth
[recursive_grid]
layers = [
{ depth = 0, grid_cols = 2, grid_rows = 2, keys = "crtn" },
{ depth = 1, grid_cols = 3, grid_rows = 3, keys = "gcrhtnmwv" },
]
OptionTypeDefaultDescription
enabledbooltrueNative depth transitions on supported platforms
duration_msint50Transition duration, in ms

Labels shrink to fit narrowing cells, keeping each cell at least label_autohide_multiplier times the font size, and hide below min_font_size. All labels in one draw share a size. Set min_font_size to font_size to never shrink. The sub-key preview follows the same rule with its own size and multiplier.

OptionTypeDefaultDescription
font_sizeint10Largest label size
font_familystring""Font family. Accepts generic aliases, and empty means the platform’s sans family
line_widthint1Grid line width
line_colorcolorderivedGrid line color
highlight_colorcolorderivedSelected cell highlight
text_colorcolorderivedLabel text
label_backgroundboolfalseBackground behind labels
label_background_colorcolorderivedLabel background
label_background_padding_xint-1Horizontal label padding, -1 for automatic
label_background_padding_yint-1Vertical label padding, -1 for automatic
label_background_border_radiusint-1Label corner radius, -1 for automatic
label_background_border_widthint1Label border width
label_charstring""Override all cell labels with a single character, such as ·. Empty uses the key
min_font_sizeint6Smallest size a label or the sub-key preview shrinks to before it hides
label_autohide_multiplierfloat1.5Shrink the label so each cell stays at least the font size times this, 0 turns it off
sub_key_previewboolfalseShow a mini-grid of the next level’s keys inside each cell
sub_key_preview_font_sizeint8Sub-key preview font size
sub_key_preview_autohide_multiplierfloat1.5The same requirement for the preview, measured against one sub-cell
sub_key_preview_text_colorcolorderivedSub-key preview text color
sub_key_preview_label_charstring""Override sub-key labels with a single character, such as ·. Empty uses the key
[recursive_grid.hotkeys] # plus the shared defaults under Per-mode hotkeys
"`" = "toggle-cursor-follow-selection"
"Space" = "action reset"
"Backspace" = "action backspace"

[[recursive_grid.app_configs]] takes bundle_id, capture_scope and hotkeys, as in grid.

Settings for bisect mode. How the mode behaves is in neru bisect.

[bisect]
capture_scope = "window"
OptionTypeDefaultDescription
enabledbooltrueTurn the mode on or off
capture_scopestring"screen"Region the session starts from: screen or window (the screen if nothing is focused). --capture-scope overrides it

The quadrant cells show whichever single-character keys are bound to the quadrant cuts.

[bisect.hotkeys] # plus the shared defaults under Per-mode hotkeys
"`" = "toggle-cursor-follow-selection"
"h" = "action bisect --direction=left"
"j" = "action bisect --direction=down"
"k" = "action bisect --direction=up"
"l" = "action bisect --direction=right"
"y" = "action bisect --direction=up_left"
"u" = "action bisect --direction=up_right"
"b" = "action bisect --direction=down_left"
"n" = "action bisect --direction=down_right"
"Space" = "action reset"
"Backspace" = "action backspace"
OptionTypeDefaultDescription
enabledbooltrueNative transition between cuts on supported platforms
duration_msint50Transition duration, in ms

The same options and defaults as [recursive_grid.ui]. label_char overrides the four quadrant labels, and label_autohide_multiplier and min_font_size shrink and then hide them. The sub_key_preview* options are accepted and do nothing.

[[bisect.app_configs]] takes bundle_id, capture_scope and hotkeys, as in grid.

Settings for vim mode. How the mode behaves is in neru vim.

[vim]
capture_scope = "screen"
[vim.ui]
cursor_color = "#FF8800AA"
[vim.keymaps.normal]
"<Space>j" = "<Plug>(jump)"
[vim.hotkeys]
"Ctrl+c" = "idle"
OptionTypeDefaultDescription
enabledbooltrueTurn the mode on or off
capture_scopestring"window"What is read: window (the screen if nothing is focused) or screen. --capture-scope overrides it
OptionTypeDefaultDescription
font_sizeint13Status bar and notice font size
font_familystring""Status bar and notice font. Accepts generic aliases, and empty means a monospaced face
cursor_colorcolorderivedBar down the cursor’s left edge. The cursor’s fill is this color at about a third of its alpha. Also the fill of the cursor’s character in the lens
selection_colorcolorderivedFill of the visual selection
match_colorcolorderivedUnderline of each search match, and outline of the one under the cursor
container_colorcolorderivedOutline of the container the cursor is in, and at a third of its opacity of the block around it. A fully transparent color hides both
status_background_colorcolorderivedBackground of the status bar
status_text_colorcolorderivedText of the status bar, and of the mode chip while vim waits on input

Vim draws jump labels and the lens as hint badges, in the font, colors, border and padding of [hints.ui]. The waiting notice takes the hint badge’s colors, border and corners, in the font above. The status bar’s mode chip is theme.accent in normal mode and theme.accent_alt in visual mode, with text in theme.on_accent_alt. While vim waits on a command, a jump, a motion or typing, the chip is an outline in the hint border color.

[vim.keymaps.normal] and [vim.keymaps.visual] map keys to other keys inside vim, the way vim’s nnoremap and xnoremap do. Both sides are in vim’s notation, such as "<Space>j", "<C-j>" or "<CR>", and letter case counts, so H and h are different keys. Both tables ship empty.

[vim.keymaps.normal]
"H" = "^"
"L" = "$"
"<Space>j" = "<Plug>(jump)"
"s" = "<Nop>"
"S" = "<Plug>(read-screen)<Plug>(jump)"
[vim.keymaps.visual]
"H" = "^"
  • The keys a mapping runs are vim’s own and never mapped again, so mapping "<Space>j" = "s" runs vim’s own s, which changes a character. Write vim mode’s commands as <Plug>(name), with the names in the table below.
  • One mapping can run several commands, in order, as S above reads the screen and then starts a jump. One key runs at most eight of them.
  • "<Nop>" makes the keys do nothing.
  • A key that starts a longer mapping waits one second for the rest of it, then runs as typed.
  • Your mapping of a key replaces vim mode’s own mapping of it, which the table below lists. A default key you map to something else no longer runs its command.
  • Mappings apply in normal and visual mode. Vim mode never maps keys typed on the : line, after an operator such as d, after f or r, during an s jump, or into the app after i.
  • Neru refuses a mapping of Escape, which always cancels and leaves. It also refuses keys it never reads, such as <Del> and <S-Left>, a name vim does not know, such as <M-j>, a <Plug> name vim mode does not have, and two spellings of one sequence, such as "<Space>j" and "<space>j". Write <lt> for a literal <. A refused mapping refuses the whole file, as any invalid option does.
  • [vim.hotkeys] runs first. A key bound there never reaches these tables.
CommandMapped by default toDoes
<Plug>(jump)sStart a jump
<Plug>(read-screen)<C-l>Read the screen again
<Plug>(left-click)<CR>, gcClick at the cursor. A count clicks that many times, up to three
<Plug>(right-click)grRight click at the cursor, with a count as above
<Plug>(middle-click)gmMiddle click at the cursor, with a count as above
<Plug>(move-mouse)ghMove the real cursor to the vim cursor
<Plug>(scroll-line-down)<C-e>Scroll the app down two lines
<Plug>(scroll-line-up)<C-y>Scroll the app up two lines
<Plug>(scroll-half-down)<C-d>Scroll the app down half the region read
<Plug>(scroll-half-up)<C-u>Scroll the app up half the region read
<Plug>(scroll-page-down)<C-f>Scroll the app down most of the region read
<Plug>(scroll-page-up)<C-b>Scroll the app up most of the region read
<Plug>(scroll-left)zhScroll the app left eight characters, or the count
<Plug>(scroll-right)zlScroll the app right eight characters, or the count
<Plug>(scroll-half-left)zHScroll the app left half the width read
<Plug>(scroll-half-right)zLScroll the app right half the width read
<Plug>(center-line)zzScroll the app until the cursor’s line is in the middle. zz runs vim’s own zz first, so a count picks the line
<Plug>(next-icon)]iMove to the next icon
<Plug>(prev-icon)[iMove to the previous icon

Visual mode maps <CR> to gs, the drag operator.

[vim.hotkeys] ships empty, because every key in vim mode is vim’s own. A key you bind there runs its action instead, and vim never sees it. Binding "Escape" means Escape no longer leaves visual mode either. A two-letter sequence such as "jk" takes its first key as the start of the sequence, so j on its own would no longer move. While vim types into the app, the keys bound here type as they would without vim. Otherwise the table follows per-mode hotkeys.

[[vim.app_configs]] takes bundle_id, capture_scope and hotkeys, as in grid.

Keyboard-driven scrolling.

[scroll]
scroll_step = 80
invert_scroll = true
OptionTypeDefaultDescription
scroll_stepint50Pixels per line scroll action
scroll_step_halfint500Pixels per half-page action
scroll_step_fullint1000000Pixels for top/bottom jump actions
invert_scrollboolfalseInvert scroll direction (for tools like Mos that reverse synthetic scroll events)
[scroll.hotkeys] # plus the shared defaults under Per-mode hotkeys
"k" = "action scroll_up"
"j" = "action scroll_down"
"h" = "action scroll_left"
"l" = "action scroll_right"
"gg" = "action go_top"
"Shift+G" = "action go_bottom"
"u" = "action page_up"
"PageUp" = "action page_up"
"d" = "action page_down"
"PageDown"= "action page_down"
FieldTypeDescription
bundle_idstringApp bundle ID
scroll_stepintscroll_step for this app
scroll_step_halfintscroll_step_half for this app
scroll_step_fullintscroll_step_full for this app
hotkeysmapper-app hotkey overrides

Picks a display by typing the label on its badge. Monitors are ordered top to bottom, then left to right.

[monitor_select]
enabled = true
characters = "asdf"
OptionTypeDefaultDescription
enabledboolfalseEnable interactive monitor picking
charactersstring"123456789"Characters used for monitor labels
OptionTypeDefaultDescription
font_sizeint96Largest badge label size. It shrinks to fit the badge, which is capped at 80% of the monitor
font_familystring""Badge label font family. Accepts generic aliases, and empty means sans
subtitle_font_sizeint18Largest monitor name size. It shrinks so a long name fits the badge
subtitle_font_familystring""Subtitle font family. Accepts generic aliases, and empty uses the label’s
border_radiusint-1Badge corner radius, -1 for automatic
padding_xint-1Horizontal padding, -1 for automatic
padding_yint-1Vertical padding, -1 for automatic
border_widthint1Badge border width
background_colorcolorderivedBadge fill color
text_colorcolorderivedLabel text color
matched_text_colorcolorderivedPartially-typed label text color
border_colorcolorderivedBadge border color
backdrop_colorcolorderivedPer-monitor overlay backdrop tint, black at 20% opacity in light and 40% in dark
subtitle_text_colorcolorderivedSubtitle text color

monitor_select does not ship the shared defaults under Per-mode hotkeys, only this one:

[monitor_select.hotkeys]
"Escape" = "idle"

Styles the pointer character Neru draws in place of the cursor. The standalone overlay, drawn when hide_cursor hides the system cursor, is macOS-only. The in-frame indicator in grid and recursive-grid overlays uses the same options on every platform.

[virtual_pointer.ui]
char = "+"
font_size = 12
OptionTypeDefaultDescription
charstring"●"Character to display
font_sizeint8Font size in points
font_familystring""Font family. Accepts generic aliases, and empty means the platform’s sans family
text_colorcolorderivedCharacter color

A transient marker drawn where a mouse action happens. Works on all platforms, and animation timing may differ slightly between them.

[mouse_action_indicator]
enabled = true
actions = ["left_click", "right_click"]
[mouse_action_indicator.ui]
shape = "square"
OptionTypeDefaultDescription
enabledboolfalseEnable indicators
actionsstring[]every click, press, release, and toggle actionTriggering actions

actions accepts any mouse button action from the action names that a mode --action accepts.

OptionTypeDefaultDescription
sizeint36Diameter in points
border_widthint2Border width
background_colorcolorderivedFill color
border_colorcolorderivedStroke color
shapestring"circle"circle or square
OptionTypeDefaultDescription
duration_msint260Animation duration, in ms
start_scalefloat0.55Starting scale
end_scalefloat1.35Ending scale
start_opacityfloat0.85Starting opacity
end_opacityfloat0.0Ending opacity
easingstring"ease_out"linear, ease_in, ease_out, ease_in_out

A floating label that follows the cursor and shows the current mode.

[mode_indicator.hints]
enabled = true
text = "H"

Each mode has a [mode_indicator.<mode>] table for scroll, hints, grid, recursive_grid, bisect, monitor_select and vim. Only scroll is shown by default, and the default text is the mode’s name in title case, such as Recursive Grid.

OptionTypeDefaultDescription
enabledboolvaries by modeShow the indicator for this mode
textstringvaries by modeLabel text
background_colorcolorderivedOverride background color
text_colorcolorderivedOverride text color
border_colorcolorderivedOverride border color
OptionTypeDefaultDescription
font_sizeint10Font size
font_familystring""Font family. Accepts generic aliases, and empty means the platform’s sans family
background_colorcolorderivedBackground with alpha
text_colorcolorderivedText color
border_colorcolorderivedBorder color
border_widthint1Border width
padding_xint-1Horizontal padding, -1 for automatic
padding_yint-1Vertical padding, -1 for automatic
border_radiusint-1Corner radius, -1 for automatic
indicator_x_offsetint20X offset from cursor, positive to the right
indicator_y_offsetint20Y offset from cursor, positive downward

Tap a modifier inside a mode to hold it for the following actions.

[sticky_modifiers]
tap_max_duration = 200
OptionTypeDefaultDescription
enabledbooltrueEnable sticky modifiers
tap_max_durationint300Longest press that counts as a tap, in ms. 0 always toggles

[sticky_modifiers.ui] takes the same options and defaults as [mode_indicator.ui], except indicator_x_offset defaults to -40 (left of the cursor).

On Linux the indicator draws ❖⇧⌥⌃. If they show as boxes, set font_family to a font with those glyphs.

Animates cursor movement. Off by default.

[smooth_cursor]
move_mouse_enabled = true
max_duration = 150
OptionTypeDefaultDescription
move_mouse_enabledboolfalseEnable animated mouse movement
stepsint10Number of animation steps
max_durationint200Longest animation, in ms
duration_per_pixelfloat0.1Ms per pixel for jumps, giving constant speed
relative_movement_durationint50Fixed duration per relative move, in ms, at least 10

relative_movement_duration applies to move_mouse_relative, which the default arrow bindings use. Each relative move takes this fixed time, so cursor speed scales with the step size. A move arriving mid-animation extends the current endpoint, so no distance is lost under key repeat or held_repeat acceleration.

Splits each scroll into chunked ease-out events. How fine a step can be depends on the platform, see Platform support.

[smooth_scroll]
enabled = true
OptionTypeDefaultDescription
enabledboolfalseEnable smooth scrolling
stepsint20Number of animation steps
max_durationint180Longest animation, in ms
duration_per_pixelfloat1.0Ms per pixel for adaptive duration
  • On Wayland, enabling it sends a continuous delta instead of wheel notches, which some apps scale differently. Trim scroll.scroll_step if the distance changes.
  • Under [held_repeat], each repeat folds in what the previous animation had not yet sent, so N repeats travel as far as N presses (within a wheel notch per repeat on X11).
  • A scroll with a different modifier set cancels the animation in flight and drops its remaining distance.

Repeats scroll, page, move_cell and snap actions while the key is held, and glides the cursor for a held move_mouse_relative (see Glide). A held snap --direction walks from element to element, one scan per repeat, so a repeat waits for the scan before it.

[held_repeat]
enabled = true
accel_enabled = true
OptionTypeDefaultDescription
enabledboolfalseMaster toggle for held-key repeat and the glide
initial_delay_msint50Delay before the first repeat, in ms
interval_msint50Interval between repeats, in ms
accel_enabledboolfalseRamp the glide’s speed up the longer the key stays held
accel_ramp_msint500Hold time to reach accel_max_multiplier, in ms
accel_max_multiplierfloat4.0Speed multiplier at full ramp
accel_targetsstring[]["move_mouse_relative"]Action names eligible for acceleration

A held key bound to a lone move_mouse_relative glides the cursor along its --dx/--dy instead of repeating, at the same angle its taps move. Speed is the length of the binding’s step per interval_ms, so 10px every 50ms is 200px/s, and --dx 30 --dy 40 steps 50px. The glide runs from key down to release, so initial_delay_ms does not apply. It eases up to speed from rest in about 120ms, and stops where you release the key. Two held keys move diagonally at the same speed, opposite keys cancel, and the larger step sets the speed. Pressing or releasing a second key bends the path over the same 120ms instead of turning in one move. A tap travels one step. The glide works across monitors, and a click during it acts at the cursor’s live position.

With accel_enabled = true, the glide speed ramps linearly to accel_max_multiplier times the binding’s speed over accel_ramp_ms. With the defaults a 10px binding reaches about 500px/s at 250ms and 800px/s from about 500ms.

  • accel_targets accepts only move_mouse_relative. Any other entry, or an empty list while accel_enabled = true, is a config error.
  • accel_enabled = true with enabled = false does nothing, and neru config validate warns.

The system tray icon and its menu.

[systray]
enabled = false
OptionTypeDefaultDescription
enabledbooltrueShow the tray icon

A change to enabled needs a daemon restart, since neru config reload keeps the icon as is. On Windows, notifications need the tray, see Platform support.

Neru always logs to the console. Set disable_file_logging = false to also write a JSON log file. Its path is under Log File Locations.

[logging]
log_level = "debug"
disable_file_logging = false
OptionTypeDefaultDescription
log_levelstring"info"Level: debug, info, warn, error
disable_file_loggingbooltrueLog to the console only. Set false to also write a JSON log file
log_filestring""Log file path when file logging is on. Empty uses the platform default path
max_file_sizeint10MB before the log file is rotated
max_backupsint5Rotated log files to keep
max_ageint30Days to keep rotated log files

A change to any [logging] option needs a daemon restart, since neru config reload keeps the logger as is.

info covers daemon start (with the config path) and stop, config reloads, and mode activation and exit. warn marks something Neru worked around, and error a failure it could not recover from. Use debug temporarily for key routing, hint generation, overlays or IPC. No level logs typed text, fed keys, exec output or config values.