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.
This application is written in Go.
There are two major directories to keep in mind:
cmd/:: command structure, contains actual main command implementationsinternal/:: 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.
In order to build both packages at the same time, run
nix build .#{nixos,nixosLegacy}.
Documentation is split into two parts:
They are both managed with a build script at doc/build.go, and with the following Makefile rules:
make gen-manpages:: generateroff-formatted man pages withscdocmake gen-site:: automatically generate settings/module docs for websitemake serve-site:: start a preview server for themdbookwebsite.
make gen-site generates two files:
- Documentation for all available settings in
config.toml - Module documentation for
services.nixos-cli, built usingnix-options-doc
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.
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 "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 re-introduce 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 at package.nix.
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.
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.
