nina

Nina is a command-line helper for NixOS. Use it to find packages, apply your configuration, roll back a generation, or check another machine over SSH.

nina search ripgrep
nina apply
nina back
nina status --all

It calls the Nix tools you already use and gives common tasks shorter names. Your configuration stays in Nix files. Nina is written in Zig and builds as a single binary with no third-party Zig dependencies; it needs Nix and the relevant system tools to carry out commands.

Install

Nina's system commands are for NixOS. Package and development commands use Nix, which needs the nix-command and flakes experimental features enabled.

Install in your user profile:

nix profile add 'https://kepr.uk/nina/archive/HEAD.tar.gz#nina'

Then run:

nina setup

Setup creates Nina's configuration if it is missing and checks the required Nix features. On NixOS, it offers to add the setting to /etc/nixos/configuration.nix; you must rebuild for it to take effect. If the install command above fails because these features are disabled, enable them in Nix first.

To build from source, you need Zig 0.16:

koh steal kepr.uk/nina
cd nina && zig build -Doptimize=ReleaseFast
sudo cp zig-out/bin/nina /usr/local/bin/nina

You can also download a source archive from releases:

tar xf nina-*.tar.gz && cd nina-*/
zig build -Doptimize=ReleaseFast
sudo cp zig-out/bin/nina /usr/local/bin/nina

nina goodbye uninstalls Nina. Run nina update to check for a newer Nina release. If your system configuration manages Nina, update it through that configuration.

Apply a configuration

nina edit opens configuration.nix in your editor. Check it before applying, or build it without switching:

nina edit
nina check
nina apply --dry
nina apply

Nina also supports flake-based system configurations. Set the machine's config directory to the directory containing your configuration.

If you need to go back, use nina back. To choose a specific generation, find its number with nina history, then run nina go <n>.

Command	What it does
nina history	Lists system generations
nina back	Rolls back one generation
nina go <n>	Switches to generation <n>
nina diff	Compares generations
nina upgrade	Updates Nix inputs or channels and rebuilds
nina clean	Removes old system generations and collects garbage

nina clean keeps the number of generations set in your config, five by default. Removing generations means you can no longer roll back to them.

Find and use packages

nina search <q> searches nixpkgs through nix search. In a terminal, results appear in an inline browser. Use the arrow keys to move, Tab for package details, Enter to select a package, and Escape to cancel. When stdin is not a terminal, search prints a plain list.

nina search ripgrep
nina install ripgrep
nina try ripgrep
nina remove ripgrep
nina list

Selecting a package in search or running nina install asks how you want to use it:

• Install it in your user profile without a system rebuild.
• Add it through your system configuration: Nina opens the editor at the package list and offers to apply your changes.
• Try it in a temporary shell without installing it.

Search and installation may need network access to fetch Nix inputs or packages. nina option <q> searches NixOS options.

Home Manager

Nina supports standalone Home Manager and Home Manager integrated into a NixOS configuration. To create a standalone configuration:

nina home init

Add --switch to activate it immediately. Nina chooses a Home Manager branch from your NixOS version and leaves an existing configuration in place.

Command	What it does
nina home apply	Applies your home configuration
nina home back	Rolls back one home generation
nina home history	Lists home generations
nina home edit	Opens home.nix
nina home check	Builds the home configuration without switching
nina home diff	Compares the latest two home generations
nina home packages	Lists packages in the home generation

When Home Manager is part of your NixOS configuration, nina home apply runs a system rebuild. Home commands operate on the local user; they do not support --on.

Configure Nina

Nina reads ~/.config/nina/config, or $XDG_CONFIG_HOME/nina/config when that environment variable is set.

editor      = hx
generations = 5
confirm     = true
teach       = false
color       = true

[machine]
name    = my-machine
config  = /etc/nixos
local   = true
default = true

Set editor to your preferred editor. generations controls how many system generations cleanup keeps. With teach = true, Nina prints the underlying commands as you work.

Nina disables color when stdout is not a terminal and respects NO_COLOR.

Work on another machine

Add a machine with an SSH host to your config:

[machine]
name    = azula
host    = azula
user    = june
ssh_key = ~/.ssh/id_ed25519

Put --on <name> after the command to select it:

nina apply --on azula
nina service logs ollama -f --on azula
nina status --all

Remote system operations use SSH and the tools on the target machine. nina status --all checks every configured machine. Use nina hello to list them.

Run hooks

Place executable scripts in ~/.config/nina/hooks/ to run before or after these operations:

pre-apply     post-apply
pre-back      post-back
pre-home      post-home
pre-upgrade   post-upgrade

Missing or non-executable hooks are skipped. If a pre-hook fails, Nina shows its last five output lines and asks whether to continue, defaulting to no. A failed post-hook produces a warning after the operation succeeds. Hooks run locally, including when the operation targets a remote machine.

For example, save this as ~/.config/nina/hooks/pre-apply to check for uncommitted changes, then make it executable with chmod +x:

#!/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

More commands

Command	What it does
nina status	Shows machine health
nina doctor	Checks for common problems
nina log	Shows Nina's operation history
nina service list	Lists systemd services
nina service logs <s>	Reads a service's journal
nina service start/stop/restart <s>	Controls a service
nina flake show	Shows flake outputs
nina flake update	Updates flake inputs
nina pin <in> <rev>	Pins a flake input to a revision
nina unpin <in>	Updates a pinned input
nina develop	Enters a development shell
nina build	Builds a flake output
nina run <p>	Runs a package
nina edit --dir	Opens the configuration directory
nina fmt	Formats the system configuration
nina info	Shows system information
nina boot	Lists boot entries

Run nina help for the full command list, nina <group> help for a group such as home or service, and nina man [topic] for the built-in manual. nina --version prints the installed version.

Build and test

From the source directory:

zig build
zig build test
zig fmt --check build.zig src/*.zig

System operations need a NixOS host for live testing. The VM test harness describes testing against disposable NixOS images.

Made by Asha Software.

Website · Source · Documentation