nixos-cli

A unified NixOS management tool.

Introduction

Tooling for nixos has become quite scattered, and as a result, NixOS can be pretty obtuse to use. There are many community tools available to fix the problem, but no all-in-one solution.

nixos-cli is exactly that - an all-in-one tool to manage any NixOS installation with ease, that consists of:

• Drop-in replacements for NixOS scripts and tools like nixos-rebuild
• Generation manager and option preview TUIs
• Many more

All available through an easy-to-use (and pretty!) interface.

High-level documentation is available as a website, while a detailed reference for each command and settings is available in the form of man pages after installation.

Development

This application is written in Go.

There are two major directories to keep in mind:

• cmd/ :: command structure, contains actual main command implementations
• internal/ :: anything that is shared between commands, categorized by functionality

Each command and subcommand MUST go in their own package and match the command tree that it implements.

All dependencies for this project are neatly provided in a Nix shell. Run nix develop .# or use direnv to automatically drop into this Nix shell on changing to this directory.

Nix Package

The Nix package is divided into two variants: an unwrapped variant and a wrapped one. The wrapped one adds dependencies such as Nix itself to the PATH, while the unwrapped package is the one that gets rebuilt when the source code/documentation is changed. This is done to avoid excessive rebuilds if Nix itself or other runtime dependencies of nixos-cli is changed.

There are four packages provided as flake package outputs:

• nixos-cli
• nixos-cli-legacy
• nixos-cli-unwrapped
• nixos-cli-legacy-uwnrapped

Only use the unwrapped packages when absolutely necessary.

In order to build both wrapped packages at the same time, run nix build .#{nixos-cli,nixos-cli-legacy}.

Legacy-style nix-build and nix-shell can also be used; this uses flake-compat under the hood.

Tests

A collection of NixOS integration tests, created using pkgs.testers.runNixOSTest is available in nix/tests. They are also exposed as flake check attributes.

To run a particular test using flakes, run nix build .#checks.<arch>.<test-name>.

If not using the flake, invoke nix-build directly using nix-build -A <test-name> to run a test.

Large features with a significant feature scope should likely have corresponding NixOS tests for them, so create more as needed. When creating a test, use a suffix .test.nix and place it in ./nix/tests, and it will be picked up as a check automatically based on the filename.

Since these tests are quite expensive to run, passing them is not an automatic CI requirement, but care should be taken to not fail the tests in this directory, and pull requests will be rejected if they are not fixed.

Documentation

Documentation is split into two parts:

• A documentation website, built using mdbook
• Manual pages (man pages), generated using scdoc

They are both managed with a build script at doc/build.go, and with the following Makefile rules:

• make gen-manpages :: generate roff-formatted man pages with scdoc
• make gen-site :: automatically generate settings/module docs for website
• make serve-site :: start a preview server for the mdbook website.

make gen-site generates two files:

• Documentation for all available settings in config.toml
• Module documentation for programs.nixos-cli, built using optnix

The rest of the site documentation files are located in doc/man.

make gen-manpages generates man pages using scdoc, and generates one additional man page file from a template: the available settings for nixos-cli-config(5).

Check the build script source for more information on how to work with this.

Versioning

Version numbers are handled using semantic versioning. They are also managed using Git tags; every version has a Git tag named with the version; the tag name does not have a preceding letter "v".

Non-released builds have a version number that is suffixed with "-dev". As such, a tag should always exist on a version number change (which removes the suffix), and the very next commit will reintroduce the suffix.

Once a tag is created and pushed, create a GitHub release off this tag.

The version number is managed inside the Nix derivation inside the nix/package directory.

CI

The application must build successfully upon every push to main, and this is a prerequisite for every patch or pull request to be merged.

Cache artifacts are published in a Cachix cache at https://watersucks.cachix.org when a release is triggered.

AI Policy

All contributions made to nixos-cli are appreciated. However, quality becomes a concern when AI is involved.

AI is a tool in the developer toolbox, and is used for code review, courtesy of CodeRabbit and their OSS program. As such, AI usage is not prohibited, but proper standards must be enforced to prevent the repository from rotting.

AI-assisted contributions will be accepted under three conditions:

1. The contributor must understand their code and be able to explain it in their pull request description and during the review process. AI-generated descriptions, comments, etc. will be rejected without consideration.
2. The contributor must demonstrate that their code works, either through proper unit/integration tests, or with picture/video evidence.
3. Autonomously-submitted code (via Claude Code or other such agentic AI tools) will be automatically rejected without consideration. This kind of drive-by contribution forces the maintainers to make the assumption that the contributor did not do their due diligence described in the previous conditions.

Additionally, AI usage is strictly prohibited for issues marked with the "good first issue" label. Those issues are meant for human contributors to get a good grasp on the codebase by doing the work on their own; using AI to do this defeats the purpose and actively does the maintainers a disservice. Please also consider this when contributing to other open-source projects.

Talk!

Join the Matrix room at #nixos-cli:matrix.org! It's open for chatting about NixOS in general, and for making it a better experience for all that involved.

I would like for this to become a standard NixOS tool, which means that I want to cater to potentially many interests. If you would like for any commands to be implemented that you think fit this project, talk to me on Matrix or file a GitHub issue.