documentation

everything she knows

A quiet reference for a cozy tool. Find what you need, take your time.

getting started

what is nina?

intro

Nina 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 v3 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

setup

Nina ships pre-built binaries for Linux and macOS via Kepr Builds. One command installs the right binary for your machine:

install

$ curl -fsSL https://kepr.uk/nina/install.sh | sh

→ auto-detects your platform, verifies checksum, installs to ~/.local/bin

steal the source

$ koh steal kepr.uk/nina

→ full source snapshot, build with: zig build -Doptimize=ReleaseSafe

(•̀ᴗ•́)و

After installing, run nina setup — it handles enabling the Nix experimental features Nina needs, no manual config editing required.

nina setup

onboarding

nina setup is your onboarding step. It checks whether Nix's experimental features are already enabled and enables them for you if not — no sudo required.

$ nina setup

What it does:

Runs before config loading — works as a true onboarding step even with no ~/.nina.conf
Checks /etc/nix/nix.conf and ~/.config/nix/nix.conf for experimental-features
If nix-command and flakes are already enabled: prints all set and exits cleanly
If not: appends experimental-features = nix-command flakes to ~/.config/nix/nix.conf, creating the file and ~/.config/nix/ directory if needed
Detects NixOS via /etc/NIXOS and shows the nix.settings.experimental-features hint for configuration.nix when relevant

( •̀ω•́ )✧

On NixOS, the permanent way to enable these features is via configuration.nix. Nina shows you the exact line to add when it detects a NixOS system.

nixos configuration.nix equivalent

# configuration.nix

nix.settings.experimental-features = [ "nix-command" "flakes" ];

first run

setup

Just type nina help at the prompt. She'll show you every command she knows. (っ˘ω˘ς )

$ nina help

:: nina nixos helper

apply rebuild and switch

back roll back one generation

search <q> find packages

install <pkg> add to profile or system

diff changes between generations

help this message

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.

commands

search & discovery

search · option

Inline 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.

nina search

nina search <query>

Search nixpkgs for packages in an 18-line inline widget — no fullscreen takeover, no context switch. Runs nix search nixpkgs under the hood.

$ nina search ripgrep

:: search nixpkgs ripgrep 3 results

ripgrep 14.1.0 recursively search directories for a regex pattern

ripgrep-all 0.10.0 ripgrep, but also search in PDFs, E-Books, ...

ripgrep-fixed 0.1.0 ripgrep with fixed-string matching

↓↑ navigate · i install · s system · t try · esc

( •̀ω•́ )✧

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

nina option

nina option <query>

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.

$ nina option logind

:: search options logind N results

packages

install · remove · profile

Install packages into your profile with a single command. Nina searches nixpkgs, shows you what it found, and asks how you want it.

nina install

nina install <pkg>

Search nixpkgs for the package, then prompt for install method. Σ(°∀° )

$ nina install neovim

:: neovim 0.10.4

[i] profile install instant no rebuild

[s] system install opens editor requires apply

[t] try now exits when done

> i

:: installing neovim profile

-> nix profile install nixpkgs#neovim

:: neovim installed available now

[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.

nina remove

nina remove <pkg>

Remove a package from your active Nix profile by name.

nina try

nina try <pkg>

Drop into a temporary nix shell with the package available. Exits cleanly — nothing is written to your profile or config.

nina list

Show packages in your active Nix profile.

nina profile

nina profile [list | install <attr> | remove <attr> | upgrade]

Low-level profile management. profile list shows all profile packages. profile upgrade upgrades all profile packages at once.

nina pin / nina unpin

nina pin <input> <commit> · nina unpin <input>

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 · back

Preview, 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.

nina diff

nina diff [<from> <to>]

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.

$ nina diff

:: gen 348 -> gen 349 kyoshi

+ neovim 0.10.4

^ ripgrep 14.0.3 -> 14.1.1

nina check

Validate your configuration with nixos-rebuild build. Catches syntax errors and missing references before they reach a running system. No activation — nothing changes.

nina apply

nina apply [--on <machine>] [--dry]

Rebuild and switch to the new generation with nixos-rebuild switch. If confirm = true in your config, Nina asks before proceeding.

$ nina apply

:: rebuilding kyoshi...

:: generation 349 [4.1s]

--on <machine> rebuild a remote machine over SSH

--dry dry-activate only — build without switching

--check validate config only, same as nina check

nina back

Roll back one generation using nixos-rebuild switch --rollback. To jump to a specific generation, use nina go <n>.

$ nina back

:: rolling back kyoshi gen 349 -> gen 348

:: done gen 348

ε-(´∀｀; )

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 · build

Inspect flake outputs, step into dev shells, build specific outputs, and manage the flake lifecycle — all with the same quiet vocabulary.

nina flake show

Show what the current directory's flake exposes — packages, apps, dev shells, NixOS configurations. Parses nix flake show --json output.

$ nina flake show

:: .

packages x86_64-linux nina

apps x86_64-linux nina

devShells x86_64-linux default

nina flake update

nina flake update [<input>]

Run nix flake update. Pass a specific input name to update only that one. Prints a confirmation when flake.lock is written.

nina flake check

Run nix flake check. Reports valid or prints the error.

nina develop

nina develop [run <cmd> | show]

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.

$ nina develop

:: entering dev shell

exit to return

nina build

nina build [<attr>]

Build a flake output with nix build. Defaults to the default attribute. Result is linked as ./result.

nina run

nina run <pkg>

Run a package without installing it. Bare names are resolved as nixpkgs#<pkg>.

inspection & care

status · service · clean

Check on the health of your system, follow service logs, inspect the store, and reclaim disk space — without jumping between different tools.

nina status

nina status [--on <machine>]

Show the current generation and reachability of the target machine.

$ nina status

:: status

kyoshi gen 349

nina doctor

nina doctor [--on <machine>]

Run a health diagnostic. Checks the nix daemon, config syntax, and channels. Prints ok / warn / fail per check.

$ nina doctor

:: diagnosing kyoshi

nix daemon ok

config syntax ok

channel ok

:: all good

nina service

Manage systemd services. service logs <name> -f follows the journal live. stop and disable prompt for confirmation when confirm = true.

$ nina service logs ollama -f

:: ollama last 50 lines kyoshi

nina store

nina store [info | gc | verify | repair | path <attr>]

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.

nina clean

nina clean [--all]

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. ( ˘ω˘ )

$ nina clean

:: cleaning kyoshi keeping 5 of 14

continue? [Y/n] y

:: freed ?

generation history

history · go · gen · log

Your 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.

nina history

List all system generations with their timestamps. The current generation is highlighted.

$ nina history

:: generations kyoshi

349 2026-05-30 09:32:01 current

348 2026-05-29 14:22:44

347 2026-05-25 11:05:33

nina go

nina go <n>

Switch to any specific generation by number using nix-env --switch-generation. Use this when nina back isn't far enough.

nina gen

nina gen [list | current | delete <n | old>]

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.

nina log

nina log [--last <n>]

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.

machine config

edit · info · channel · boot

Edit 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.

nina edit

nina edit [hardware]

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.

$ nina edit

:: opening /etc/nixos/configuration.nix

-> vim /etc/nixos/configuration.nix

run nina check to validate before applying

nina fmt

nina fmt [--check]

Format configuration.nix with nixpkgs-fmt. --check reports whether formatting is needed without writing.

nina info

Show the NixOS version, kernel version, and uptime of the target machine.

nina channel

nina channel [list | add <url> [<name>] | remove <name> | update]

Manage Nix channels. channel list is the default. channel update runs nix-channel --update.

nina boot

List boot entries from the bootloader. Shows the current entry and all available generations.

nina repl

Launch nix repl with nixpkgs loaded. Type :q to exit.

(ˊᗜˋ)

nina edit uses the editor value from ~/.nina.conf (default: vim). Set it to your editor of choice and Nina will use it everywhere.

remote machines

--on · hello · doctor

The same voice, even over SSH. Every Nina command accepts --on <machine> and behaves identically on a remote host. No separate tooling, no context switching.

the --on flag

nina <command> --on <machine>

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.

$ nina apply --on azula

✦ rebuilding azula over ssh

· building generation 193

generation 193.

$ nina service logs ollama -f --on azula

✦ following logs for ollama on azula

[info] serving on 0.0.0.0:11434

configuring machines

Define remote machines in ~/.nina.conf:

# ~/.nina.conf

[machine]

name = azula

host = june@azula

ssh_key = ~/.ssh/id_ed25519

fleet commands

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.

reference

configuration

~/.nina.conf

Nina's config file lives at ~/.nina.conf. 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. (´ω｀)

full example

# ~/.nina.conf

editor = nvim

generations = 5

confirm = true

teach = false

color = true

# local machine (default)

[machine]

name = kyoshi

config = /etc/nixos

local = true

default = true

# remote machine over SSH

[machine]

name = azula

config = /etc/nixos

host = june@azula

ssh_key = ~/.ssh/id_ed25519

all options

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
`[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 · moods

Nina 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.

(˶ᵔ ᵕ ᵔ˶)

ready

Quiet and present. Nina is ready for input and not trying too hard to be noticed.

shows when: at the prompt, in search, and in gentle idle moments

( •̀ω•́ )✧

focused

A little brighter, still tidy. Nina is doing something active and keeping the runway short.

shows when: loading search results, starting a rebuild, entering a busier command

(ﾉ◕ヮ◕)ﾉ

bright

A small burst of good news. Something finished cleanly and Nina lets herself be pleased for a second.

shows when: after a clean apply, a copied result, or a nice little success

(っ˘ω˘ς )

gentle

A softer expression for transitions, exits, and quieter actions where the UI should settle back down.

shows when: leaving a search, cleaning up, or easing out of a command

(｡•́︿•̀｡)

sorry

Not dramatic, just honest. Something needs attention, and Nina leaves the details where you can see them.

shows when: failed lookups, service trouble, or command errors

( ´•̥̥̥ω•̥̥̥` )

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 · workflow

A few patterns that make daily NixOS life a little smoother. (*˘︶˘*)

daily driver routine

A quiet morning with Nina:

# update flake inputs and preview changes

$ nina flake update

$ nina diff

# apply if the diff looks good

$ nina apply

safe exploration

Try a package without committing to it:

$ nina try bat

:: trying bat exit when done

→ bat is available in this shell only, gone when you exit

fleet rollout

Push the same config change to multiple machines:

$ nina apply --on kyoshi

:: generation 349 [4.1s]

$ nina apply --on azula

:: generation 193 [6.3s]

generation archaeology

Something broke and you want to find when:

$ nina history

→ find the last known-good generation number

$ nina diff 344 349

→ see what changed across those generations

$ nina go 344

:: done gen 344

home-manager

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.

useful aliases

# in your shell config

alias ns="nina search"

alias no="nina option"

alias na="nina apply"

alias nd="nina diff"

alias nb="nina back"

(≧◡≦)

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.