1# nina23**the best way to use nixos.**45Nina wraps the full NixOS workflow in plain, memorable verbs — packages, rebuilds, generations, flakes, services, remote machines. Written in Zig. Zero dependencies. One binary.67```8$ nina search ripgrep9$ nina apply10$ nina back11$ nina status --all12```1314---1516## install1718**nix profile** (recommended — instant, per-user, no `sudo`):1920```sh21nix profile add 'https://kepr.uk/nina/archive/HEAD.tar.gz#nina'22```2324Remove any time with `nina goodbye`.2526**koh** (build from source via koh):2728```sh29koh steal kepr.uk/nina30cd nina && zig build -Doptimize=ReleaseFast31sudo cp zig-out/bin/nina /usr/local/bin/nina32```3334**source archive** (download and build manually):3536Download the source archive from [kepr.uk/nina/releases](https://kepr.uk/nina/releases), then:3738```sh39tar xf nina-*.tar.gz && cd nina-*/40zig build -Doptimize=ReleaseFast41sudo cp zig-out/bin/nina /usr/local/bin/nina42```4344**linux · nixos 24.05+** — requires `nix-command` and `flakes` experimental features. 45Run `nina setup` on first use to enable them automatically.4647---4849## the commands you'll actually use5051```52nina apply rebuild and switch to the new configuration53nina apply --dry preview what would change without switching54nina back roll back to the previous generation55nina go <n> jump to any generation by number56nina history list all generations57nina clean remove old generations and free store space5859nina search <q> search nixpkgs inline — browse, install, or try60nina option <q> search NixOS options inline61nina install <p> add a package — profile (instant) or system config62nina remove <p> remove a package from profile or system config63nina try <p> run a package without installing it64nina list show installed packages6566nina home apply apply home-manager config67nina home back roll back one home-manager generation68nina home history list home-manager generations69nina home edit open home.nix70nina home check validate home config without switching71nina home diff compare the latest two home generations72nina home packages list packages managed by home-manager7374nina status machine health at a glance75nina status --all health across every configured machine76nina doctor diagnose common issues77nina diff what changed between generations78nina log operation history7980nina service list list systemd services and their state81nina service logs <s> journal logs for a service82nina service start/stop/restart <s>8384nina flake show inspect flake outputs85nina flake update update lock files86nina pin <in> <rev> pin a flake input to a commit87nina unpin <in> release a pinned flake input88nina develop enter a dev shell89nina build build a flake output90nina run <p> run a package without installing9192nina edit open configuration.nix in your editor93nina edit --dir open the config directory in your editor94nina check validate config without switching95nina fmt format nix files96nina info nixos version, kernel, uptime97nina boot boot entries9899nina help all commands100nina --version version info101```102103---104105## hooks106107Nina runs optional executable hook scripts before and after state-changing commands.108Create them in `~/.config/nina/hooks/`:109110```111pre-apply post-apply112pre-back post-back113pre-home post-home114pre-upgrade post-upgrade115```116117Missing hooks are ignored. Hook files must be executable (`chmod +x`) to run.118If a pre-hook exits non-zero, Nina shows the last five output lines and asks119whether to continue, defaulting to no. If a post-hook exits non-zero, Nina shows120a warning after the command's success line.121122Example: stop `nina apply` when your config has uncommitted changes.123124```sh125126127if git -C ~/nixos-config status --porcelain | grep -q .; then128 echo "uncommitted changes - commit before applying"129 exit 1130fi131```132133---134135## multi-machine136137Any command runs on a remote machine with `--on <name>`. Configure machines in `~/.config/nina/config`:138139```ini140[machine]141name = kyoshi142config = /etc/nixos143local = true144default = true145146[machine]147name = azula148host = azula149user = june150ssh_key = ~/.ssh/id_ed25519151```152153```154nina apply --on azula155nina service logs ollama -f --on azula156nina status --all157```158159```160:: status161162 kyoshi gen 348 3m ago 42 GB163 azula gen 192 14m ago 18 GB164```165166---167168## search that stays at the prompt169170`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).171172```173:: search nixpkgs ripgrep 12 results174175 > ripgrep 14.1.1 free fast line-oriented search176 ripgrep-all 0.9.6 free search across file formats177 ugrep 6.0.0 free grep compatible ripgrep alt178179 ripgrep 14.1.1 free180 recursively search directories for a regex pattern181 attr pkgs.ripgrep182183 enter install tab info [up/down] nav esc cancel184```185186---187188## install that actually works189190`nina install` uses `nix search nixpkgs` directly — no external API, no network dependency after your first channel update, no silent failures. Works offline.191192Two install paths, your choice:193194- **profile** — instant. package available immediately. no rebuild.195- **system** — opens your editor at the right line in `configuration.nix`, then offers to apply.196197---198199## config200201`~/.config/nina/config` — plain text, no surprises:202203```ini204editor = hx205generations = 5206confirm = true207teach = false208color = true209210[machine]211name = my-machine212config = /etc/nixos213local = true214default = true215```216217`teach = true` prints the underlying nix command after each operation so you learn while you work.218219---220221## what nina outputs222223```224:: rebuilding kyoshi...225226 -> [build output]227228:: generation 14 [42.3s]229```230231```232:: error: 'firefocks' not found in nixpkgs233 -> try: nina search firefox234```235236Pink `::` 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`.237238---239240## built by241242[asha software](https://asha.software) — hope in every line of code.243244**[nina.asha.software](https://nina.asha.software)** · [source](https://kepr.uk/nina) · [docs](https://nina.asha.software/docs)