Installation
Every way to install, update and remove Neru. Supported systems are in Platform support. After installing, continue with Getting started.
Install script
Section titled “Install script”The recommended method on every platform. Run it again to update.
# macOS and Linuxcurl -fsSL https://raw.githubusercontent.com/y3owk1n/neru/main/scripts/install.sh | bash# Windowsirm https://raw.githubusercontent.com/y3owk1n/neru/main/scripts/install.ps1 | iexIt installs the binary, Neru.app on macOS, man pages, shell completions and,
if you accept, the login service. It checks every download against its
published .sha256 file.
Every flag, and where each file goes, is in Install script reference.
Channels and versions
Section titled “Channels and versions”The default is the latest stable release. Nightly is rebuilt from
every push to main. A rerun stays on the installed channel, and the script
asks before it switches channels.
curl -fsSL https://raw.githubusercontent.com/y3owk1n/neru/main/scripts/install.sh | bash -s -- --version v1.52.0curl -fsSL https://raw.githubusercontent.com/y3owk1n/neru/main/scripts/install.sh | bash -s -- --channel nightly# flags need a script block. NERU_CHANNEL, NERU_VERSION and NERU_YES work with plain `irm | iex`& ([scriptblock]::Create((irm https://raw.githubusercontent.com/y3owk1n/neru/main/scripts/install.ps1))) -Channel nightlyHomebrew
Section titled “Homebrew”macOS only. Report tap problems at y3owk1n/homebrew-tap. Stable and nightly cannot be installed side by side, so uninstall one first.
brew install --cask y3owk1n/tap/neru # stable, upgrade with brew upgrade --caskbrew install --cask y3owk1n/tap/neru-nightly # nightly, upgrade with brew upgrade --cask --greedyNightly upgrades need --greedy, or brew skips rolling releases.
oku installs Neru from the repo’s
oku.pkg.toml on macOS, Linux and Windows. It takes the release zip for your
machine, checks it against the release’s build attestation and .sha256
file, and adds man pages and shell completions. It installs stable releases
only.
oku add -g github:y3owk1n/neru --service # with the login service-g adds it to your global list. Inside a project directory oku installs
only the program and skips Neru.app and the service. To keep it in your
oku.toml instead:
[packages]neru = { ref = "github:y3owk1n/neru", service = true }- macOS: oku copies
Neru.appto~/Applications, andneruon yourPATHruns that copy, so the CLI and the daemon share its Accessibility and Screen Recording permissions. macOS may ask for them again after an update. - Login service:
--serviceregisters the daemon with launchd on macOS, Task Scheduler on Windows and a systemd user unit on Linux.oku servicecontrols it. - Login service on Linux: needs oku 0.18.0 or later. oku’s unit starts
and stops with your graphical session, like the one
neru services installwrites, so the same session setup applies. With an older oku, leave out--serviceand useneru services install. - With
neru services installon Linux: its unit points at the build in oku’s store, so afteroku update nerurunneru services uninstallandneru services installagain. - One service only: use oku’s service or
neru services install, not both.neru services installdoes not see oku’s service. - From source:
oku add -g github:y3owk1n/neru --from-sourcebuilds the release tag with Go, which oku installs, and writesfrom_source = trueto your list so every update builds too. A Linux machine with musl libc has no release zip and always builds. The build needs what From source lists, and oku names any missing part. - Latest main:
oku add -g github:y3owk1n/neru#neru-mainbuilds the newest commit ofmaininstead of a release, and needs the same tools. Its version is the date and commit, such as2026.10.09-a73243f, andoku update nerutakes the newest commit. It installs the sameneru, so remove the release package first. Add--serviceto keep Neru starting at login. - Updating:
oku update neru.
Prebuilt binaries
Section titled “Prebuilt binaries”Download neru-<os>-<arch>.zip from
GitHub Releases. <os> is
darwin, linux or windows, and <arch> is arm64 (Apple Silicon, ARM64)
or amd64 (Intel, x86_64). Every archive has a .sha256 file, and releases
from v1.51.0 on carry a build provenance attestation:
gh attestation verify neru-darwin-arm64.zip --repo y3owk1n/neruUnpack neru, or Neru.app on macOS, anywhere you like. A manual install has
no completions or login service. Add them with
Shell completions and Login service,
or run the install script with --from DIR on the unpacked tree.
The flake provides modules for nix-darwin, NixOS and home-manager, and an overlay with two packages:
pkgs.neru: the release zip for your system (default).pkgs.neru-source: built from the flake’s source.
Add the input inputs.neru.url = "github:y3owk1n/neru"; to flake.nix,
then the overlay and one module:
modules = [ { nixpkgs.overlays = [ neru.overlays.default ]; } neru.darwinModules.default # or neru.nixosModules.default, neru.homeManagerModules.default { services.neru.enable = true; services.neru.settings = { hotkeys = { "Primary+Shift+Space" = "hints --action left_click"; "Primary+Shift+G" = "grid --action left_click"; }; }; }];Module options
Section titled “Module options”Shared by all three modules. Set only one of settings, config and
configFile, or the build fails.
| Option | Default | Description |
|---|---|---|
services.neru.enable | false | Install Neru and its login service |
services.neru.package | pkgs.neru | Package to use. pkgs.neru-source builds from source |
services.neru.settings | {} | Config as a Nix attribute set, written out as TOML |
services.neru.config | configs/default-config.toml | Config as an inline TOML string |
services.neru.configFile | null | Path to an existing config.toml |
services.neru.extraEnvironment | {} | Extra environment for the service. Merged over a default PATH with the Nix binary directories. Setting PATH replaces it |
Service options per module:
| Module | Options | Service |
|---|---|---|
| nix-darwin | launchd.enable (true), launchd.keepAlive (true) | launchd user agent, RunAtLoad |
| NixOS | systemd.restart ("on-failure"), systemd.restartSec (5) | systemd user service on graphical-session.target |
| home-manager | launchd.enable, launchd.keepAlive on macOS. systemd.enable (true), systemd.restart, systemd.restartSec on Linux | Same as above, and writes ~/.config/neru/config.toml |
Nix notes
Section titled “Nix notes”-
Package only: to manage the service yourself, skip the module and add
pkgs.nerutoenvironment.systemPackages(nix-darwin or NixOS, with the overlay), orneru.packages.${system}.defaulttohome.packages(home-manager, no overlay). Use.sourceto build from source. -
Completions: the packages install bash, zsh and fish completions on macOS only. On Linux, add them with Shell completions.
-
Updating: run
nix flake update neru, then rebuild. -
Older Go in nixpkgs:
pkgs.neru-sourceneeds Go 1.27, which nixpkgs 26.05 and unstable provide. Neru’s code uses Go 1.27 language features, so an older Go cannot build it. On an older nixpkgs, use the prebuiltpkgs.neru. -
Codesigning
pkgs.neru-sourceon macOS:pkgs.neruis pre-signed.pkgs.neru-sourcehas only the Go linker’s signature, without the hardened runtime entitlements. Sign it after activation with the bundledContents/Resources/Neru.entitlements. For nix-darwin:{system.activationScripts.postActivation.text = ''app="/Applications/Nix Apps/Neru.app"if [ -e "$app" ]; then/usr/bin/codesign --force --sign - \--entitlements "$app/Contents/Resources/Neru.entitlements" \--options runtime --timestamp=none "$app"fi'';}For home-manager, run the same command from
home.activation.signNeru = lib.hm.dag.entryAfter [ "copyApps" ] '' ... ''withapp="$HOME/Applications/Home Manager Apps/Neru.app".
From source
Section titled “From source”| Platform | Needs |
|---|---|
| All | Go 1.27+ and just |
| macOS | Xcode Command Line Tools (xcode-select --install) for the Objective-C bridge |
| Linux | A C compiler and the -dev/-devel packages the CGO build links against, listed in Development setup |
| Windows | Git for Windows, whose sh runs the just recipes. The build has CGO off, so no C compiler |
just install builds Neru into build/dist/ and runs the install script on
that tree, so a source install lands in the same places as a release.
git clone https://github.com/y3owk1n/neru.git && cd nerujust install # asks before the login service and other optional stepsjust install -y # accept every promptOn Windows just install runs scripts/install.ps1, so use the PowerShell
flag spelling (-Yes, -NoService). A source build reports a git describe
version, so the script treats it as a source install. It asks before a
release replaces a source install, and before a source install replaces a
release. Other build options are in the
Development guide.
Shell completions
Section titled “Shell completions”The install script, just install and the Nix packages on macOS write
completions for you. Otherwise run neru completion:
neru completion bash > ~/.local/share/bash-completion/completions/neruneru completion zsh > ~/.zsh/completions/_neru # needs ~/.zsh/completions on your fpathneru completion fish > ~/.config/fish/completions/neru.fishneru completion powershell | Out-String | Invoke-Expression # add to your $PROFILE to keep itLogin service
Section titled “Login service”The install script offers this. To add it later:
neru services installWhat it registers on each platform, and when it refuses, is under
neru services.
Set up with an agent
Section titled “Set up with an agent”Three skills for coding agents such as Claude Code, Codex and Cursor.
neru-ask answers what Neru can do and which command or option does it.
neru-setup-config writes, validates and applies your config.
neru-build-integration helps you build a script or program on Neru’s CLI,
IPC socket or Go client. All three read the installed version’s help, man
pages and docs, so no checkout is needed.
npx skills add y3owk1n/neru --skill neru-ask --skill neru-setup-config --skill neru-build-integrationAdd -g to install them for every project.
An agent with no skill installed can run neru agent-guide instead. It
prints a short guide written for the installed build. Point the agent at it
with one line in its instructions file, such as ~/.claude/CLAUDE.md or
AGENTS.md:
- Before doing anything with Neru, run `neru agent-guide` and follow it.A chat assistant that cannot run commands can read it too. Copy the output,
such as with neru agent-guide | pbcopy on macOS, and paste it in with your
question.
Install script reference
Section titled “Install script reference”| bash | PowerShell | Env | Effect |
|---|---|---|---|
--channel stable|nightly | -Channel | NERU_CHANNEL | Release channel. Default: the installed one, else stable |
--version vX.Y.Z | -Version | NERU_VERSION | Pin a stable release (implies stable) |
--from DIR | -From | NERU_FROM | Install a local just dist tree instead of downloading. just install uses this |
--bin-dir DIR | NERU_BIN_DIR | Where neru goes. Default /usr/local/bin (macOS), ~/.local/bin (Linux) | |
--app-dir DIR | NERU_APP_DIR | macOS: where Neru.app goes. Default /Applications | |
--no-service | -NoService | Never register or start the login service | |
--no-completions | -NoCompletions | Skip shell completions | |
--no-man | Skip man pages | ||
--force | -Force | Reinstall the same version | |
--uninstall | -Uninstall | Remove everything a previous run installed. Config is kept | |
--purge | -Purge | With uninstall, also delete config, data and logs (each confirmed) | |
-y, --yes | -Yes | NERU_YES=1 | Accept every prompt. Required when no terminal is attached |
What it installs
Section titled “What it installs”| Platform | Binary and app | Man pages | Completions | Login service |
|---|---|---|---|---|
| macOS | Neru.app in /Applications, neru symlinked into /usr/local/bin | /usr/local/share/man/man1 | bash, zsh and fish, whichever you have | launchd agent |
| Linux | ~/.local/bin/neru | ~/.local/share/man/man1 | per-user bash, zsh and fish paths | systemd user service |
| Windows | %LOCALAPPDATA%\Programs\neru\neru.exe, added to your user PATH, plus a Start Menu shortcut | none | PowerShell profile | Task Scheduler logon task |
- macOS: it asks for sudo only when a target directory is not writable.
- Linux: it runs the downloaded binary once first. If a library is
missing, it lists the names, points at Linux setup, and stops
without changing anything. It offers the
inputgroup that Wayland keyboard capture needs. - Windows: it offers to set the
RemoteSignedexecution policy for your user, since PowerShell loads no profile underRestricted. Decline and it skips completion. - zsh: it writes
~/.zsh/completions/_neruand prints thefpathline for~/.zshrcif that directory is not on yourfpath. - Any: it stops a registered login service while it replaces the binary. It refuses to run over a Homebrew or Nix install and prints the command to use instead.
Uninstallation
Section titled “Uninstallation”Install script
Section titled “Install script”The script removes what it installed: the login service, the app or binary,
the PATH link, man pages, completions, and on Windows the Start Menu shortcut
and PATH entry. Config, data and logs stay unless you add --purge, which
asks before deleting each directory.
curl -fsSL https://raw.githubusercontent.com/y3owk1n/neru/main/scripts/install.sh | bash -s -- --uninstall # add --purge to delete config, data and logsjust uninstall # from a checkout, takes the same -y and --purge& ([scriptblock]::Create((irm https://raw.githubusercontent.com/y3owk1n/neru/main/scripts/install.ps1))) -UninstallOn macOS, the Accessibility and Screen Recording entries stay in System
Settings, under Privacy & Security. Remove them by hand if you are not
reinstalling. On Linux, the script leaves your input group membership,
since other evdev tools may need it.
Homebrew, Nix and oku
Section titled “Homebrew, Nix and oku”Homebrew: brew uninstall --cask y3owk1n/tap/neru, or neru-nightly. Nix:
remove the module or package from your configuration and rebuild. oku:
oku remove -g neru, which also stops the service and deletes Neru.app
from ~/Applications.
Manual
Section titled “Manual”macOS:
neru services uninstallrm -rf /Applications/Neru.apprm /usr/local/bin/nerurm -f ~/.config/fish/completions/neru.fish ~/.zsh/completions/_neru \ ~/.local/share/bash-completion/completions/nerurm -f /usr/local/share/man/man1/neru*.1rm -rf ~/.config/neru ~/Library/Application\ Support/neru ~/Library/Logs/neruLinux:
neru services uninstallrm -f ~/.local/bin/nerurm -f ~/.local/share/bash-completion/completions/neru ~/.zsh/completions/_neru \ ~/.config/fish/completions/neru.fishrm -f ~/.local/share/man/man1/neru*.1rm -rf ~/.config/neru ~/.local/share/neru ~/.local/state/neru
# only if nothing else needs itsudo gpasswd -d "$USER" inputTo remove the systemd unit by hand, find where it lives in Systemd user service.
Windows:
neru services uninstallStop-Process -Name neru -Force -ErrorAction SilentlyContinueRemove-Item "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Neru.lnk"Remove-Item "$env:LOCALAPPDATA\Programs\neru" -RecurseRemove-Item "$env:APPDATA\neru" -RecurseRemove-Item "$env:LOCALAPPDATA\neru" -RecurseRemove the PATH entry under Edit environment variables for your account in
Settings, or use just uninstall. Avoid setx, which truncates the value at
1024 characters and flattens other tools’ %VAR% entries.