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

Configuring Neru

How to create, edit and apply your Neru config. Neru reads one TOML file, and anything the file leaves out keeps its built-in default, so write only what you want to change. Every option is in the configuration reference.

Create the file

Section titled “Create the file”
Terminal window
neru config init

This writes the full default config with every option commented out, to ~/.config/neru/config.toml, or %APPDATA%\neru\config.toml on Windows. On Linux its [hotkeys] table is commented out too. Pass --force to overwrite an existing file, or -c PATH to write somewhere else.

Apply your changes

Section titled “Apply your changes”

After editing it:

Terminal window
neru config validate   # check the file, no daemon needed
neru config reload     # apply it to the running daemon

A reload rebuilds hotkeys, overlays and services. If the file has an error, the reload fails and Neru keeps the previous config.

Options read only at startup, such as [logging] and [systray] enabled, need you to restart the daemon.

Change one value without editing the file

Section titled “Change one value without editing the file”

neru config set changes one value on the running daemon right away, and neru config reset undoes it.

Terminal window
neru config set hints.hint_characters "qwerty"
neru config set scroll.scroll_step 25
neru config reset scroll.scroll_step

Values that only make sense together, such as a grid’s size and keys, are set with --no-reload and applied with one reload at the end:

Terminal window
neru config set --no-reload recursive_grid.grid_cols 3
neru config set --no-reload recursive_grid.grid_rows 3
neru config set --no-reload recursive_grid.keys "gcrhtnmwv"
neru config reload
  • neru config dump | jq shows the dotted path of every setting.
  • Only single values can be set: strings, numbers, booleans, colors and string lists. Setting a list replaces it rather than adding to it.
  • Edit hotkey tables and app_configs in the file itself.
  • config set and config reset also work as hotkey steps, so one key can switch a setting, see Recipes.

How the layers combine

Section titled “How the layers combine”

Each layer overrides the one before it:

  1. Built-in defaults for your platform.
  2. config.toml, the file you edit.
  3. The override file, which holds every neru config set change. It sits next to your config and takes its name, so config.toml gets config.override.toml.

To drop every neru config set change, delete the override file and run neru config reload.

Where Neru looks for the file

Section titled “Where Neru looks for the file”

At launch Neru uses the first of these that exists:

  1. $XDG_CONFIG_HOME/neru/config.toml when XDG_CONFIG_HOME is set, otherwise %APPDATA%\neru\config.toml on Windows or ~/.config/neru/config.toml elsewhere
  2. ~/.config/neru/config.toml, so a dotfiles config works on Windows as-is
  3. ~/.neru.toml
  4. neru.toml in the current directory
  5. config.toml in the current directory

neru launch -c /path/to/config.toml skips the search. neru status --json | jq -r .config shows which file the running daemon read.

Next steps

Section titled “Next steps”