documentation
everything she knows
A quiet reference for a cozy tool. Find what you need, take your time.
what is nina?
introNina is a NixOS Intuitive Navigation Assistant — a gentle command-line tool that wraps the full NixOS workflow in one quiet, consistent voice.
She handles package search, rebuilds, flakes, services, generation history, and remote machines — all without dropping you into a different screen, switching tools, or making you memorise long nixos-rebuild incantations.
Nina is a ground-up rewrite in Zig. Zero runtime dependencies. A single binary. Runs the same on any NixOS machine.
The goal is simple: NixOS should feel like home. Nina is one step toward that.
Nina stays inline at your prompt. Search results, install confirmations, diff previews — everything comes to you. You never leave the shell you're already in.
installation
setupNina is a Nix flake. Two ways to install:
Both methods require nix-command and flakes to be enabled. Add this to ~/.config/nix/nix.conf (or /etc/nix/nix.conf on NixOS):
Or run nina setup after installing — she'll add the line for you.
Then:
After installing, run nina setup — it makes sure the Nix features Nina needs are turned on, and on NixOS walks you through the one config line.
nina setup
onboardingnina setup is your onboarding step. It makes sure Nix's experimental features — nix-command and flakes — are enabled, which is all Nina needs to search and install packages. If they're already on, it prints all set and exits.
Nina shows you the exact line and offers to add it to /etc/nixos/configuration.nix — the declarative, permanent home for these features:
Press y and Nina appends it for you (keeping a .nina-bak backup). Prefer to do it yourself? Press n and Nina shows you the line to paste and where it goes. Either way it ends with one step:
…and then you're ready to use Nina.
Nina writes experimental-features = nix-command flakes to ~/.config/nix/nix.conf (creating the file if needed). No sudo, and it takes effect in your next shell.
first run
setupJust type nina help at the prompt. She'll show you every command she knows. (っ˘ω˘ς )
Then try nina hello to see the machines Nina has configured, or jump straight to nina search to find a package.
From here, search for a package, apply a change, or just wander through the tips section to see what's possible.
search & discovery
search · optionInline search that never takes over your screen. Results appear right below the prompt, and you navigate them with the keyboard. Press esc any time to go back to what you were doing.
Search nixpkgs for packages in an 18-line inline widget — no fullscreen takeover, no context switch. Runs nix search nixpkgs under the hood.
keys: ↓↑ or jk move through results · i / Enter profile install · s system install (opens editor) · t try ephemerally · c copy attr to clipboard · Esc / q exit without action
Search NixOS options in the same inline widget. Navigation and copy work the same as package search. Install actions are not available for options — copy the snippet and add it to your config manually.
packages
install · remove · profileInstall packages into your profile with a single command. Nina searches nixpkgs, shows you what it found, and asks how you want it.
Running nina pkg or nina profile or nina channel with no subcommand shows a subcommand list. nina pkg help does the same.
Search nixpkgs for the package, then prompt for install method. Σ(°∀° )
[i] profile install — runs nix profile install nixpkgs#attr. Available immediately, no rebuild needed.
[s] system install — opens configuration.nix in your editor at the systemPackages line. Add the package, save, and Nina asks whether to apply.
[t] try now — drops you into a nix shell with the package available. Gone when you exit.
Remove a package from your active Nix profile by name.
Drop into a temporary nix shell with the package available. Exits cleanly — nothing is written to your profile or config.
Show packages in your active Nix profile.
Low-level profile management. profile list shows all profile packages. profile upgrade upgrades all profile packages at once.
Explain why a package is installed by showing its dependency chain. An alias for nina pkg why <pkg>.
Pin or unpin a flake input to a specific commit. nina unpin runs nix flake update on that input to release the pin.
system changes
diff · apply · backPreview, apply, and roll back changes to your NixOS system. Nina shows you exactly what will change before it happens, and arms a rollback the moment things go sideways.
Compare two generations using nix store diff-closures. Without arguments, compares the previous generation to the current one. Pass two generation numbers to compare any two.
Validate your configuration with nixos-rebuild build. Catches syntax errors and missing references before they reach a running system. No activation — nothing changes.
Rebuild and switch to the new generation with nixos-rebuild switch. If confirm = true in your config, Nina asks before proceeding.
On flake-based systems where your config directory contains a flake.nix, Nina automatically passes --flake <config> to nixos-rebuild. No configuration needed.
--on <machine> rebuild a remote machine over SSH --dry dry-activate only — build without switching --check validate config only, same as nina check Roll back one generation using nixos-rebuild switch --rollback. To jump to a specific generation, use nina go <n>.
Generations are immutable snapshots. nina back always has somewhere to go, and nina go <n> can reach any point in your history.
flakes & dev shells
flake · develop · buildInspect flake outputs, step into dev shells, build specific outputs, and manage the flake lifecycle — all with the same quiet vocabulary.
Running nina flake with no subcommand shows a subcommand list. nina flake help does the same.
Show what the current directory's flake exposes — packages, apps, dev shells, NixOS configurations. Parses nix flake show --json output.
Run nix flake update. Pass a specific input name to update only that one. Prints a confirmation when flake.lock is written.
Unpinned inputs — including https://kepr.uk/nina/archive/HEAD.tar.gz, if you've pinned Nina as a flake input rather than installing via nix profile — are cached locally by Nix for tarball-ttl seconds (an hour, by default) no matter what's actually changed upstream. If an update looks like a no-op and you know there's something newer, run nix flake update <input> --refresh directly — nina flake update doesn't forward flags yet.
Run nix flake check. Reports valid or prints the error.
Enter the flake's dev shell with nix develop. Type exit to return. develop run <cmd> runs a single command without an interactive shell. develop show builds without entering.
Build a flake output with nix build. Defaults to the default attribute. Result is linked as ./result.
Run a package without installing it. Bare names are resolved as nixpkgs#<pkg>.
inspection & care
status · service · cleanCheck on the health of your system, follow service logs, inspect the store, and reclaim disk space — without jumping between different tools.
Running nina service or nina store with no subcommand shows a subcommand list. nina service help does the same.
Show the current generation and reachability of the target machine.
Home Manager generation is shown when Nina detects a standalone Home Manager installation.
Run a health diagnostic. Checks the nix daemon, config syntax, and channels. Prints ok / warn / fail per check.
Manage systemd services. service logs <name> -f follows the journal live. stop and disable prompt for confirmation when confirm = true.
All service commands accept --user to target user-managed systemd services instead of system services.
Inspect and maintain the Nix store. store info (default) shows total size, live paths, and reclaimable space. store gc runs garbage collection. store path <attr> evaluates a store path for a nixpkgs attribute.
Remove old generations and run garbage collection. Keeps the number of generations set by generations in your config (default: 5). --all removes all old generations regardless of that setting. ( ˘ω˘ )
generation history
history · go · gen · logYour system's whole story is saved in generations. Browse them, compare them, travel back to any of them. Nothing is gone until you clean it up.
Running nina gen with no subcommand shows a subcommand list. nina gen help does the same.
List all system generations with their timestamps. The current generation is highlighted.
Switch to any specific generation by number using nix-env --switch-generation. Use this when nina back isn't far enough.
gen list is an alias for history. gen current prints the current generation number and nothing else. gen delete <n> removes a specific generation; gen delete old removes all non-current generations.
Show Nina's operation log from ~/.local/share/nina/nina.log. Displays the last 50 entries by default. Use --last N to show more or fewer.
Generations are your safety net. Apply freely, knowing you can always go back. nina history shows the whole story. nina go takes you there.
home manager
home · init · apply · back · historyNina manages your Home Manager configuration with the same vocabulary as your system. All nina home commands work with standalone Home Manager and NixOS module setups. Nina detects which mode you're using automatically.
Bootstrap Home Manager for the first time. Runs nix run home-manager/<branch> -- init, which creates ~/.config/home-manager/home.nix with a starter configuration. After running, edit home.nix and apply with nina home apply.
Passing --switch activates the configuration immediately after creating it — no separate nina home apply needed. Pass a directory path to initialise into a custom location instead of ~/.config/home-manager.
If ~/.config/home-manager/home.nix already exists, Nina refuses to overwrite it and points you at nina home apply instead.
Apply your Home Manager configuration. Runs home-manager switch under the hood. --dry builds without activating.
On NixOS module setups (where home-manager is managed by nixos-rebuild), Nina redirects you to nina apply which rebuilds both system and home config together.
Roll back to the previous Home Manager generation using home-manager switch --rollback.
List all Home Manager generations with timestamps. The current generation is marked.
Show what changed between the last two Home Manager generations using nix store diff-closures.
Validate your Home Manager configuration with home-manager build without activating.
Open ~/.config/home-manager/home.nix in your configured editor.
List packages managed by Home Manager in your current generation.
The same apply → diff → back pattern works for your home config, just as it does for your system. Nina uses the same verbs so you don't have to learn a second vocabulary.
machine config
edit · info · channel · bootEdit your configuration safely, inspect the running system, manage channels, and set boot defaults — all without needing to remember the right file path or nixos-rebuild flag.
Open configuration.nix in your configured editor (default: vim). Pass hardware to open hardware-configuration.nix instead. After saving, run nina check to validate before applying.
Format configuration.nix with nixpkgs-fmt. --check reports whether formatting is needed without writing.
Show the NixOS version, kernel version, and uptime of the target machine.
Manage Nix channels. channel list is the default. channel update runs nix-channel --update.
On flake-based systems, nina upgrade updates flake inputs and rebuilds instead of running nix-channel --update.
List boot entries from the bootloader. Shows the current entry and all available generations.
Launch nix repl with nixpkgs loaded. Type :q to exit.
nina edit uses the editor value from ~/.config/nina/config (default: vim). Set it to your editor of choice and Nina will use it everywhere.
remote machines
--on · hello · doctorThe same voice, even over SSH. Every Nina command accepts --on <machine> and behaves identically on a remote host. No separate tooling, no context switching.
Any Nina command runs on a configured remote machine. The machine name matches an entry in your Nina config file, or falls back to your SSH config.
Define remote machines in ~/.config/nina/config:
nina hello list all configured machines and their kind (local / ssh) nina status --on <machine> show generation and uptime for a remote machine nina doctor --on <machine> run a full health diagnostic on any machine nina apply --on <machine> rebuild and switch a remote machine over SSH Nina keeps remote work from turning into a whole new personality. Same verbs, same little reassurances, same sense of where you are.
hooks
pre · postNina can run optional executable scripts before and after state-changing commands. Hooks live in ~/.config/nina/hooks/. Missing hooks are ignored, and files that are not executable are treated as absent.
pre-apply runs before nina apply, pre-back before nina back, pre-home before nina home apply, and pre-upgrade before nina upgrade. The matching post-* hooks run only after the command succeeds.
If a pre-hook exits non-zero, Nina shows the exit code and the last five lines of hook output, then asks whether to continue. That prompt defaults to no, even if confirm = false, because a hook failure usually means something the user explicitly cares about.
If a post-hook fails, Nina prints a warning after the success line. The original command already succeeded, so the hook warning does not turn the operation into a failure.
This hook stops nina apply when your NixOS config has uncommitted changes:
Make hook scripts executable with chmod +x ~/.config/nina/hooks/pre-apply. Nina creates the hooks directory automatically the first time it checks for hooks.
configuration
~/.config/nina/configNina's config file lives at ~/.config/nina/config (XDG). The format is plain key=value, one per line. Comments start with #. All settings are optional — Nina works out of the box with no config file. (´ω｀)
If you have an existing ~/.nina.conf from an earlier version, Nina migrates it to ~/.config/nina/config automatically on first run.
| option | type | default | description |
|---|---|---|---|
editor | string | vim | editor command Nina opens for nina edit |
generations | integer | 5 | how many generations to keep when running nina clean |
confirm | bool | true | prompt before destructive operations. empty input or non-'n' = yes |
teach | bool | false | print the underlying nix commands Nina runs (prefixed with =) |
color | bool | true | enable ANSI colors. also respects the NO_COLOR environment variable |
flake | bool | auto-detected | set to true if your config directory contains a flake.nix. Nina detects this automatically |
[machine] name | string | local | name used with --on <name> |
[machine] config | string | /etc/nixos | path to the directory containing configuration.nix |
[machine] local | bool | true | run commands locally. set automatically to false when host is given |
[machine] default | bool | false | use this machine when no --on flag is given |
[machine] host | string | — | SSH destination (user@host or just host) |
[machine] user | string | — | SSH user, if not included in host |
[machine] ssh_key | string | — | path to SSH private key. ~ expands to $HOME |
expressions ♡
kaomoji · moodsNina uses a few small kaomoji expressions instead of a mascot. They stay tucked into the UI, show a little feeling, and leave the work itself readable.
The rule is simple: calm most of the time, brighter when something lands, softer when something goes wrong.
A warm, quiet welcome. Nina is ready to help and not making a fuss about it.
Settling in and getting to work. Something meaningful is beginning.
Something that was broken is working again. A small celebration for persistence.
Calm satisfaction. A rollback landed cleanly and the system is in good hands.
Light and tidy. The work is done and things look better than before.
Everything checked out. A quiet joy that the system is healthy.
A gentle close. Nothing went wrong — it's just time to step out.
Something went sideways, and Nina is honest about it. Details are right there with her.
If you prefer a quieter experience, set color = false in your config. Nina will still show everything — just without the ANSI palette.
tips & recipes
patterns · workflowA few patterns that make daily NixOS life a little smoother. (*˘︶˘*)
A quiet morning with Nina:
Try a package without committing to it:
Push the same config change to multiple machines:
Something broke and you want to find when:
Nina manages Home Manager directly with nina home. Apply your home config, roll it back, browse generations, and inspect packages — all with the same verbs as the rest of Nina.
When something goes wrong, nina back is always there. When you're not sure what to try next, nina diff shows you the picture. And when things go right, Nina keeps the terminal feeling light.