1# nina23Nina 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.45```sh6nina search ripgrep7nina apply8nina back9nina status --all10```1112It 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.1314## Install1516Nina's system commands are for NixOS. Package and development commands use Nix, which needs the `nix-command` and `flakes` experimental features enabled.1718Install in your user profile:1920```sh21nix profile add 'https://kepr.uk/nina/archive/HEAD.tar.gz#nina'22```2324Then run:2526```sh27nina setup28```2930Setup 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.3132To build from source, you need Zig 0.16:3334```sh35koh steal kepr.uk/nina36cd nina && zig build -Doptimize=ReleaseFast37sudo cp zig-out/bin/nina /usr/local/bin/nina38```3940You can also download a source archive from [releases](https://kepr.uk/nina/releases):4142```sh43tar xf nina-*.tar.gz && cd nina-*/44zig build -Doptimize=ReleaseFast45sudo cp zig-out/bin/nina /usr/local/bin/nina46```4748`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.4950## Apply a configuration5152`nina edit` opens `configuration.nix` in your editor. Check it before applying, or build it without switching:5354```sh55nina edit56nina check57nina apply --dry58nina apply59```6061Nina also supports flake-based system configurations. Set the machine's `config` directory to the directory containing your configuration.6263If you need to go back, use `nina back`. To choose a specific generation, find its number with `nina history`, then run `nina go <n>`.6465| Command | What it does |66| --- | --- |67| `nina history` | Lists system generations |68| `nina back` | Rolls back one generation |69| `nina go <n>` | Switches to generation `<n>` |70| `nina diff` | Compares generations |71| `nina upgrade` | Updates Nix inputs or channels and rebuilds |72| `nina clean` | Removes old system generations and collects garbage |7374`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.7576## Find and use packages7778`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.7980```sh81nina search ripgrep82nina install ripgrep83nina try ripgrep84nina remove ripgrep85nina list86```8788Selecting a package in search or running `nina install` asks how you want to use it:8990- Install it in your user profile without a system rebuild.91- Add it through your system configuration: Nina opens the editor at the package list and offers to apply your changes.92- Try it in a temporary shell without installing it.9394Search and installation may need network access to fetch Nix inputs or packages. `nina option <q>` searches NixOS options.9596## Home Manager9798Nina supports standalone Home Manager and Home Manager integrated into a NixOS configuration. To create a standalone configuration:99100```sh101nina home init102```103104Add `--switch` to activate it immediately. Nina chooses a Home Manager branch from your NixOS version and leaves an existing configuration in place.105106| Command | What it does |107| --- | --- |108| `nina home apply` | Applies your home configuration |109| `nina home back` | Rolls back one home generation |110| `nina home history` | Lists home generations |111| `nina home edit` | Opens `home.nix` |112| `nina home check` | Builds the home configuration without switching |113| `nina home diff` | Compares the latest two home generations |114| `nina home packages` | Lists packages in the home generation |115116When 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`.117118## Configure Nina119120Nina reads `~/.config/nina/config`, or `$XDG_CONFIG_HOME/nina/config` when that environment variable is set.121122```ini123editor = hx124generations = 5125confirm = true126teach = false127color = true128129[machine]130name = my-machine131config = /etc/nixos132local = true133default = true134```135136Set `editor` to your preferred editor. `generations` controls how many system generations cleanup keeps. With `teach = true`, Nina prints the underlying commands as you work.137138Nina disables color when stdout is not a terminal and respects `NO_COLOR`.139140## Work on another machine141142Add a machine with an SSH host to your config:143144```ini145[machine]146name = azula147host = azula148user = june149ssh_key = ~/.ssh/id_ed25519150```151152Put `--on <name>` after the command to select it:153154```sh155nina apply --on azula156nina service logs ollama -f --on azula157nina status --all158```159160Remote system operations use SSH and the tools on the target machine. `nina status --all` checks every configured machine. Use `nina hello` to list them.161162## Run hooks163164Place executable scripts in `~/.config/nina/hooks/` to run before or after these operations:165166```text167pre-apply post-apply168pre-back post-back169pre-home post-home170pre-upgrade post-upgrade171```172173Missing 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.174175For example, save this as `~/.config/nina/hooks/pre-apply` to check for uncommitted changes, then make it executable with `chmod +x`:176177```sh178179180if git -C ~/nixos-config status --porcelain | grep -q .; then181 echo "uncommitted changes - commit before applying"182 exit 1183fi184```185186## More commands187188| Command | What it does |189| --- | --- |190| `nina status` | Shows machine health |191| `nina doctor` | Checks for common problems |192| `nina log` | Shows Nina's operation history |193| `nina service list` | Lists systemd services |194| `nina service logs <s>` | Reads a service's journal |195| `nina service start/stop/restart <s>` | Controls a service |196| `nina flake show` | Shows flake outputs |197| `nina flake update` | Updates flake inputs |198| `nina pin <in> <rev>` | Pins a flake input to a revision |199| `nina unpin <in>` | Updates a pinned input |200| `nina develop` | Enters a development shell |201| `nina build` | Builds a flake output |202| `nina run <p>` | Runs a package |203| `nina edit --dir` | Opens the configuration directory |204| `nina fmt` | Formats the system configuration |205| `nina info` | Shows system information |206| `nina boot` | Lists boot entries |207208Run `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.209210## Build and test211212From the source directory:213214```sh215zig build216zig build test217zig fmt --check build.zig src/*.zig218```219220System operations need a NixOS host for live testing. The [VM test harness](test/vm/README.md) describes testing against disposable NixOS images.221222Made by [Asha Software](https://asha.software).223224[Website](https://nina.asha.software) · [Source](https://kepr.uk/nina) · [Documentation](https://nina.asha.software/docs)