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”neru config initThis writes the default config, with every option set to its default value,
to the first path in Where Neru looks for the file
that applies to you. Since a missing key keeps its default, you can delete
every line you do not change. On Linux the [hotkeys] table is commented
out. See Bind your first hotkey.
The flags are under neru config init.
The file starts with a #:schema line, which lets Taplo and the Even Better
TOML extension complete keys and flag mistakes. See
Editor support.
Where Neru looks for the file
Section titled “Where Neru looks for the file”At launch Neru uses the first of these that exists:
$XDG_CONFIG_HOME/neru/config.tomlwhenXDG_CONFIG_HOMEis set, on any platform, otherwise%APPDATA%\neru\config.tomlon Windows~/.config/neru/config.toml, so a dotfiles config works on Windows as-is~/.neru.tomlneru.tomlin the current directoryconfig.tomlin the current directory
neru launch -c /path/to/config.toml skips the search. Neru reads a file
outside this list, such as one written with neru config init -c PATH, only
when you pass the same -c to neru launch. The login service runs plain
neru launch, so it reads only this list.
neru status --json | jq -r .config shows which file the running daemon read.
Apply your changes
Section titled “Apply your changes”After editing it:
neru config validate # check the file, no daemon neededneru config reload # apply it to the running daemonRun neru config validate after every edit. Besides errors, it prints
warnings for unknown keys, options that do nothing on this platform, and
deprecated keys. The file still loads with them, and a reload only writes
them to the log.
A reload rebuilds hotkeys, overlays and services. If the file has an error, the reload fails and Neru keeps the previous config. At launch, an error stops Neru instead. It shows the error, prints it to stderr, and exits.
Options read only at startup, such as [logging] and [systray] enabled,
take effect after you 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.
neru config set hints.hint_characters "qwerty"neru config set scroll.scroll_step 25neru config reset scroll.scroll_stepSet values that only make sense together, such as a grid’s size and keys,
with --no-reload, then apply them with one reload at the end:
neru config set --no-reload recursive_grid.grid_cols 3neru config set --no-reload recursive_grid.grid_rows 3neru config set --no-reload recursive_grid.keys "gcrhtnmwv"neru config reloadneru config dump prints the running config as nested JSON. The command
below lists the dotted path of every value it holds, with lists and per-theme colors whole:
neru config dump | jq -r 'def p: if type == "object" and (.light | type) != "string" then to_entries[] | [.key] + (.value | p) else [] end; p | join(".")'- 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_configsin the file itself. config setandconfig resetalso 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:
- Built-in defaults for your platform.
config.toml, the file you edit.- The override file, which holds every
neru config setchange. It sits next to your config and takes its name, soconfig.tomlgetsconfig.override.toml.
To drop every neru config set change, delete the override file and run
neru config reload.
Next steps
Section titled “Next steps”- Recipes for ready-made configs.
- How bindings work before writing your own hotkey tables.
- Configuration reference for every option.