README.md
nina
the best way to use nixos.
Nina wraps the full NixOS workflow in plain, memorable verbs — packages, rebuilds, generations, flakes, services, remote machines. Written in Zig. Zero dependencies. One binary.
$ nina search ripgrep
$ nina apply
$ nina back
$ nina status --all
install
nix profile (recommended — instant, per-user, no sudo):
nix profile add 'https://kepr.uk/nina/archive/HEAD.tar.gz#nina'
Remove any time with nina goodbye.
koh (build from source via koh):
koh steal kepr.uk/nina
cd nina && zig build -Doptimize=ReleaseFast
sudo cp zig-out/bin/nina /usr/local/bin/nina
source archive (download and build manually):
Download the source archive from kepr.uk/nina/releases, then:
tar xf nina-*.tar.gz && cd nina-*/
zig build -Doptimize=ReleaseFast
sudo cp zig-out/bin/nina /usr/local/bin/nina
linux · nixos 24.05+ — requires nix-command and flakes experimental features.
Run nina setup on first use to enable them automatically.
the commands you'll actually use
nina apply rebuild and switch to the new configuration
nina apply --dry preview what would change without switching
nina back roll back to the previous generation
nina go <n> jump to any generation by number
nina history list all generations
nina clean remove old generations and free store space
nina search <q> search nixpkgs inline — browse, install, or try
nina option <q> search NixOS options inline
nina install <p> add a package — profile (instant) or system config
nina remove <p> remove a package from profile or system config
nina try <p> run a package without installing it
nina list show installed packages
nina home apply apply home-manager config
nina home back roll back one home-manager generation
nina home history list home-manager generations
nina home edit open home.nix
nina home check validate home config without switching
nina home diff compare the latest two home generations
nina home packages list packages managed by home-manager
nina status machine health at a glance
nina status --all health across every configured machine
nina doctor diagnose common issues
nina diff what changed between generations
nina log operation history
nina service list list systemd services and their state
nina service logs <s> journal logs for a service
nina service start/stop/restart <s>
nina flake show inspect flake outputs
nina flake update update lock files
nina pin <in> <rev> pin a flake input to a commit
nina unpin <in> release a pinned flake input
nina develop enter a dev shell
nina build build a flake output
nina run <p> run a package without installing
nina edit open configuration.nix in your editor
nina edit --dir open the config directory in your editor
nina check validate config without switching
nina fmt format nix files
nina info nixos version, kernel, uptime
nina boot boot entries
nina help all commands
nina --version version info
hooks
Nina runs optional executable hook scripts before and after state-changing commands.
Create them in ~/.config/nina/hooks/:
pre-apply post-apply
pre-back post-back
pre-home post-home
pre-upgrade post-upgrade
Missing hooks are ignored. Hook files must be executable (chmod +x) to run.
If a pre-hook exits non-zero, Nina shows the last five output lines and asks
whether to continue, defaulting to no. If a post-hook exits non-zero, Nina shows
a warning after the command's success line.
Example: stop nina apply when your config has uncommitted changes.
#!/usr/bin/env sh
# ~/.config/nina/hooks/pre-apply
if git -C ~/nixos-config status --porcelain | grep -q .; then
echo "uncommitted changes - commit before applying"
exit 1
fi
multi-machine
Any command runs on a remote machine with --on <name>. Configure machines in ~/.config/nina/config:
[machine]
name = kyoshi
config = /etc/nixos
local = true
default = true
[machine]
name = azula
host = azula
user = june
ssh_key = ~/.ssh/id_ed25519
nina apply --on azula
nina service logs ollama -f --on azula
nina status --all
:: status
kyoshi gen 348 3m ago 42 GB
azula gen 192 14m ago 18 GB
search that stays at the prompt
nina search opens an inline widget — no fullscreen takeover. Browse results, see versions and licenses, then press enter to install the highlighted package (choosing profile, system, or try afterward).
:: search nixpkgs ripgrep 12 results
> ripgrep 14.1.1 free fast line-oriented search
ripgrep-all 0.9.6 free search across file formats
ugrep 6.0.0 free grep compatible ripgrep alt
ripgrep 14.1.1 free
recursively search directories for a regex pattern
attr pkgs.ripgrep
enter install tab info [up/down] nav esc cancel
install that actually works
nina install uses nix search nixpkgs directly — no external API, no network dependency after your first channel update, no silent failures. Works offline.
Two install paths, your choice:
- profile — instant. package available immediately. no rebuild.
- system — opens your editor at the right line in
configuration.nix, then offers to apply.
config
~/.config/nina/config — plain text, no surprises:
editor = hx
generations = 5
confirm = true
teach = false
color = true
[machine]
name = my-machine
config = /etc/nixos
local = true
default = true
teach = true prints the underlying nix command after each operation so you learn while you work.
what nina outputs
:: rebuilding kyoshi...
-> [build output]
:: generation 14 [42.3s]
:: error: 'firefocks' not found in nixpkgs
-> try: nina search firefox
Pink :: marks Nina's voice. Green for success. Red for errors. Yellow for warnings. Color auto-disables when stdout is not a TTY. Respects NO_COLOR.
built by
asha software — hope in every line of code.