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

```sh
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:

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

Then run:

```sh
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:

```sh
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](https://kepr.uk/nina/releases):

```sh
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:

```sh
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.

```sh
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:

```sh
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.

```ini
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:

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

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

```sh
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:

```text
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`:

```sh
#!/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:

```sh
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](test/vm/README.md) describes testing against disposable NixOS images.

Made by [Asha Software](https://asha.software).

[Website](https://nina.asha.software) · [Source](https://kepr.uk/nina) · [Documentation](https://nina.asha.software/docs)