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.
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. No channels, no overlays, no nixpkgs pin needed. Just two ways to get her:
Nina is flake-friendly and works on NixOS 24.05 and newer. Nix experimental features flakes and nix-command must be enabled.
If you prefer managing tools through your system configuration:
first run
setupJust type nina at the prompt. She'll introduce herself and show you what she can do. (っ˘ω˘ς )
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 matching your query. Results stay inline — no fullscreen takeover.
--limit N show N results (default: 10) --channel <name> search a specific channel (default: nixpkgs) --json output raw JSON, skip the UI Search NixOS options inline. Navigate results, copy a snippet to the clipboard, or insert directly into your configuration.
keyboard navigation: ↓↑ move through results · i installs/inserts · t tries the package (ephemeral) · c copies to clipboard · d shows detail · esc exits without doing anything
packages
install · remove · profileInstall and remove packages without memorising store paths or profile flags. Nina handles fuzzy matching when the name is close but not exact.
Install a package into your active profile. If the name doesn't match exactly, Nina shows you the closest options and lets you pick. Σ(°∀° )
--try install ephemerally — gone when the shell closes --profile <name> install to a named profile instead of default --on <machine> install on a remote machine via SSH Remove a package from your profile. Like install, Nina uses fuzzy matching if the name is slightly off.
Manage named Nix user profiles. Useful if you want to keep work and personal tool sets separate.
Pin a package to a specific version, or release a pin. Helpful when you need an older version while the rest of the system updates.
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.
Show what would change if you applied right now. Compares the current config against the running system, or two specific generations against each other.
Dry-run the build. Catches syntax errors, missing files, and config mistakes before they reach your running system. No changes are made.
Rebuild the system and switch to the new generation. Nina prompts for confirmation, shows a brief diff, and arms a rollback timer if anything looks wrong after switching.
--on <machine> rebuild a remote machine over SSH --boot set the new generation as boot default, don't switch now --no-confirm skip the confirmation prompt (scripts, CI) Roll back to the previous generation. With --to, you can jump to any specific generation by number.
Before applying, Nina always takes a backup of your configuration.nix. Even if the build goes through and something is wrong, nina back brings you home.
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.
Show what a flake exposes — packages, apps, dev shells, NixOS modules. Works on the current directory or any flake reference.
Enter the flake's dev shell. Spawns a subshell with all the dev dependencies available. Type exit to return to your regular shell.
Build a flake output. Result is linked as ./result in the current directory.
Update the flake lock file. Pass a specific input name to update only that one.
When you run nina develop, the dango does a little dance. It's a small thing. It's a good thing.
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.
Show the health of your active machine — current generation, running services, any failed units. With --all, shows a fleet overview across all configured machines.
Manage systemd services. Actions: start, stop, restart, status, logs. The logs action accepts -f to follow.
Inspect the Nix store. Query packages by name, show dependency closures, or list paths by disk usage.
Garbage collect old build results and unused store paths. Keeps the last N generations (default: 4). Reports how much space was recovered. ( ˘ω˘ )
--keep N keep the last N generations (default: 4) --all remove all old generations, keep only the current --dry-run show what would be removed without doing it 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.
List all system generations with timestamps and a brief summary of what changed.
Switch to any generation by number. The same as nina back but for any point in your history, not just the previous one.
Show details about the current generation — number, timestamp, installed packages, and kernel version.
Show the changes between generations in chronological order. A clean changelog of your system over time.
Generations are your safety net. Apply freely, knowing you can always go back. nina history shows the whole story. nina go takes you there.
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 editor. Nina automatically creates a timestamped backup before you start, shows a diff when you save, and prompts whether to apply.
Show a summary of the running system: hostname, current generation, kernel version, NixOS version, uptime, and disk usage.
Manage Nix channels. List what's configured, add new channels, remove old ones, or update all channels at once.
Set the default boot generation in the bootloader without switching right now. Useful when you want to test a change only on the next reboot.
nina edit respects your $EDITOR environment variable. Set it to your favourite editor and Nina will meet you there.
remote machines
--on · mood · 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.toml:
nina status --all health overview across all configured machines nina mood check the dango's mood on each remote machine nina hello ping all machines and confirm they're reachable nina doctor run a full diagnostic across the fleet Nina keeps remote work from turning into a whole new personality. Same verbs, same little reassurances, same sense of where you are.
configuration
config.tomlNina's config file lives at ~/.config/nina/config.toml. All settings are optional — if the file doesn't exist, Nina uses sensible defaults and works fine out of the box. (´ω｀)
| option | type | default | description |
|---|---|---|---|
core.default_machine | string | hostname | machine Nina operates on by default |
core.confirm_apply | bool | true | prompt before applying system changes |
core.confirm_rollback | bool | true | prompt before rolling back |
core.show_dango | bool | true | show the dango character at the prompt |
core.animations | bool | true | enable all animations (also respects prefers-reduced-motion) |
search.limit | integer | 10 | default number of results shown in search |
search.channel | string | "nixpkgs" | default channel for package search |
clean.keep_generations | integer | 4 | generations to keep when running nina clean |
machines.<name>.host | string | — | SSH connection string (user@host) |
machines.<name>.key | string | ~/.ssh/id_ed25519 | path to the SSH private key |
the dango ♡
moods · feelingsThe dango is Nina's little companion — an animated ASCII rice dumpling who sits at your prompt and shows you how things are going. She has feelings. They're good ones, mostly.
She appears whenever Nina is doing something, and her mood reflects what's happening. It's a small thing. It makes the terminal feel a little less lonely.
Calm and present. Nina is ready, watching, waiting for you to tell her what to do. A gentle breathing motion that says everything is fine.
Arms up, bouncing. Something went right. A build succeeded, an apply finished cleanly, the fleet is healthy. She's celebrating with you.
Head drooping, still. Something needs attention. A build failed, a service is down, a package wasn't found. She's not panicking — just honest.
Sweeping side to side, stick swishing. She's working. Garbage collecting, editing your config, following a log stream — steady, focused work.
Arms up, spinning, full of joy. She loves dev shells. The moment you step into one, she can't help herself. It's her favourite thing.
You can turn the dango off with core.show_dango = false in your config, if you prefer a quieter experience. She understands. She won't take it personally.
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 three days ago and you're not sure when:
Nina works alongside home-manager. She manages NixOS system config; home-manager handles your user environment. They don't get in each other's way. (˶ᵔ ᵕ ᵔ˶) Run Nina for system changes, home-manager for dotfiles and user packages.
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, the dango lets you know.