NixOS Management Without the Scattered Toolkit

If you've spent any time with NixOS, you know the feeling: you need to rebuild the system, so you reach for nixos-rebuild. Then you want to inspect a generation, so you dig into the Nix store manually or hunt down a separate TUI tool. The ecosystem has grown organically, and that means the tooling has grown scattered. nixos-cli is a unified command-line tool that aims to replace that collection of scripts and utilities with a single, consistent interface.

What It Does

nixos-cli is an all-in-one management tool for NixOS installations, written in Go. It provides drop-in replacements for existing NixOS scripts like nixos-rebuild, along with generation management and option preview TUIs—all accessible through a single CLI. The project is structured around two main code directories: cmd/ for command implementations and internal/ for shared functionality between commands.

The project ships as a Nix flake with four package outputs: a wrapped version (nixos-cli) that includes runtime dependencies like Nix itself in the PATH, an unwrapped version for when you need finer control, and legacy variants of both for compatibility with older Nix tooling. The split between wrapped and unwrapped is a deliberate design choice to avoid unnecessary rebuilds when Nix or other runtime dependencies change.

Why It's Cool

The value proposition here is straightforward but important: NixOS has a tooling fragmentation problem, and this project directly addresses it.

• One command to rule them. Instead of remembering which script handles rebuilds, which handles generations, and which handles option previews, you get a single entry point. The project explicitly positions itself as a replacement for nixos-rebuild and similar scattered tools, which means less context switching when you're managing a system.

• TUI support built in. Generation management and option preview are provided as terminal user interfaces. This is a practical touch—while raw NixOS workflows are terminal-based, they often lack the interactive feedback that makes system management feel less opaque. Having a TUI for browsing generations or options means you can visually navigate what's available rather than grepping through store paths.

• Thoughtful packaging design. The wrapped/unwrapped package split is a smart engineering decision. By keeping the unwrapped package (which contains the actual Go binary) separate from the wrapped package (which adds runtime dependencies), the project avoids triggering full rebuilds when only Nix itself is updated. This matters in practice because Nix evolves frequently, and you don't want to recompile the entire CLI every time.

• Documentation as first-class output. The project generates both a website using mdbook and man pages using scdoc, with a build script in doc/build.go managing both. This dual approach means you get readable web docs for high-level understanding and man pages for quick reference in the terminal—the right tool for each context.

How to Try It

The project is available as a Nix flake. If you're using flakes, you can build it directly:

nix build .#{nixos-cli,nixos-cli-legacy}

This builds both the standard and legacy wrapped packages simultaneously. If you need the unwrapped versions, you can build those separately, but the README advises using them only when absolutely necessary.

For development, the project provides a Nix shell with all dependencies:

nix develop .#

Or set up direnv to automatically enter the shell when you change into the directory.

To run the NixOS integration tests (which are created using pkgs.testers.runNixOSTest), use:

nix build .#checks.<arch>.<test-name>

If you're not using flakes, the legacy nix-build path works too:

nix-build -A <test-name>

You can find the full source and documentation at github.com/water-sucks/nixos, with high-level documentation hosted on the project website and detailed command references available as man pages after installation.

Final Thoughts

nixos-cli is for anyone who finds themselves juggling multiple NixOS management tools and wishing for something more cohesive. It's not trying to reinvent NixOS—it's trying to make the existing experience less fragmented. The project is still under active development (the README notes that large features should have corresponding NixOS tests), but the core idea is sound. If you're tired of reaching for five different scripts to manage your NixOS systems, this is worth a look.

Follow @githubprojects for more developer tools and open source projects.