nixos-cli

Nixos-CLI: A Unified Management Tool for NixOS

Introduction: Why another tool, and what is nixos-cli?

In the ever-evolving ecosystem of NixOS tooling, the landscape can feel fragmented. Different scripts, helpers, and community projects often address narrow problems rather than offering a cohesive experience. nixos-cli emerged to be an all-in-one solution: a unified command-line interface that makes managing any NixOS installation simpler, predictable, and more enjoyable. Think of it as a drop-in replacement for core NixOS scripts and tools such as nixos-rebuild, combined with a generation manager, option preview interfaces, and a suite of utilities all accessible through a clean, approachable interface. The project aims not only to provide practical functionality but also to present a high-quality experience—from the design of its command structure to the aesthetics of its interface.

What you can expect from nixos-cli

• A single, cohesive interface for common NixOS management tasks, replacing scattered scripts and ad hoc workflows.
• A generation manager that helps you preview and switch system generations with confidence.
• A set of drop-in replacements for familiar NixOS commands, designed to be familiar to users while offering enhanced ergonomics.
• A focus on extensibility and future growth, with architecture designed to accommodate new features and options over time.
• Accessible high-level documentation through a website, plus detailed man pages that document each command and setting after installation.

Technical foundation: Go, modular design, and a developer-friendly structure

Nixos-cli is implemented in Go, a language chosen for strong performance, reliability, and straightforward cross-compilation. The project organizes its codebase into two main areas that developers should keep in mind:

• cmd/: This directory houses the actual command structure and main command implementations. Each command and subcommand is developed as its own package, aligning with the command tree the tool exposes to users.
• internal/: Shared functionality lives here, organized by purpose. This can include utilities for configuration handling, UI components, or integration with Nix tooling.

A key design principle is that every command and subcommand must be isolated in its own package and must map cleanly to the command tree it implements. This makes the project easier to understand, test, and extend. For developers exploring nixos-cli, the code structure communicates intent clearly and reduces the cognitive load when adding new commands or evolving existing ones.

Development and local environment

From a developer’s perspective, the project emphasizes reproducibility and isolation. All dependencies can be managed in a Nix shell, and there are convenient commands to drop into that environment automatically:

• nix develop .# to enter a development shell with the necessary dependencies and toolchain.
• direnv can be used to automatically drop into the Nix shell when changing into the repository directory, ensuring a consistent development environment without manual setup.

Nix packaging: wrapped vs unwrapped, and the flake story

The Nix package for nixos-cli is deliberately split into two variants—wrapped and unwrapped—to optimize build behavior and to minimize unnecessary rebuilds:

• Wrapped variant: Includes dependencies such as Nix in the PATH, making it straightforward to run in environments where those dependencies are not pre-provisioned.
• Unwrapped variant: The one that gets rebuilt when the source code or documentation changes, designed to minimize rebuild churn for version-controlled development.

There are four flake package outputs provided:

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

The naming here preserves the historical and compatibility aspects of the project. In practice, you typically want to use the unwrapped package only when absolutely necessary. For building multiple variants at once, a convenient command is:

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

This approach harmonizes the development flow with the unique needs of Nix-based packaging, ensuring that developers can experiment with different configurations without destabilizing the main, user-facing artifact.

Tests and quality assurance: practical integration tests

Quality is addressed through a collection of NixOS integration tests, designed to exercise real-world scenarios. The tests are:

• Located under nix/tests, where they can also be exposed as flake check attributes for convenient running in a Flakes-based workflow.
• Named with suffixes like .test.nix and placed directly into ./nix/tests so that the test suite collects them automatically during build or check runs.

How to run tests in Flakes or non-Flake contexts:

• With Flakes: nix build .#checks.. to run a particular test suite.
• Without Flakes: nix-build -A to execute a test directly.

The project notes that some tests are expensive to run and not strictly mandatory for CI to pass. Nevertheless, they are essential for ensuring the integrity of larger features, so contributors are encouraged to add tests where the scope warrants them and to keep tests maintainable.

Documentation: two-part approach that covers both reference and learning

Documentation is intentionally split into two complementary parts:

• A documentation website built with mdBook, providing a high-level overview, tutorials, and settings documentation in a friendly format.
• Manual pages (man pages) generated from scDoc, offering traditional Unix-style references for users who prefer system-wide documentation.

A build script at doc/build.go coordinates the generation of both outputs. The Makefile supports several useful targets:

• make gen-manpages: generate roff-formatted man pages from documentation written with scdoc. It also generates an additional man page from a template for the available settings of nixos-cli-config(5).
• make gen-site: automatically generate website content for settings and module documentation at settings/modules level. In particular, it creates documentation for all settings found in config.toml and module documentation for program entries such as programs.nixos-cli, generated using optNix.
• make serve-site: starts a local preview server for the generated mdBook website so you can review changes before publishing.

In addition to the site and man pages, the project keeps its internal and external docs aligned. The content for site documentation lives in doc/src, while the site’s dynamic documentation for settings and modules is produced by the build system, ensuring that the website reflects the actual capabilities and configuration options of nixos-cli.

Versioning and release process: semantic versioning and Git tagging

Version management follows semantic versioning and a careful release discipline to ensure clarity about changes and compatibility. Key points include:

• Version numbers are semantic: MAJOR.MINOR.PATCH, with meaningful increments emphasizing compatibility, feature additions, and bug fixes.
• Git tags correspond to released versions and are named exactly by the version number, without a leading “v.”
• Non-released builds carry a suffix of "-dev" to convey their development state.
• A tag must exist when a version changes (to remove the -dev suffix for the release) and the subsequent commit will reintroduce the suffix for ongoing development.
• Once a release is prepared, create and push a GitHub release associated with that tag.

The version information is embedded in the Nix derivation under nix/package/unwrapped.nix, providing a single source of truth for the runtime version that users will see when they install nixos-cli.

CI and distribution: ensuring reproducible builds and accessible artifacts

Continuous integration is a core part of ensuring that nixos-cli remains reliable as changes accumulate. The project’s CI requirements include:

• Building successfully on every push to the main branch, ensuring that the primary code path remains healthy.
• Publishing cache artifacts in a Cachix cache (watersucks.cachix.org) when a release is triggered. This accelerates users’ installations by providing prebuilt binaries.

By combining deterministic builds with a cache-based distribution approach, nixos-cli aims to provide quick, repeatable installation experiences for users across different environments and operating systems.

AI policy and community standards: contributing responsibly

A thoughtful and explicit policy governs AI usage in contributions. Key points include:

• AI can be used as a tool in the developer toolbox for tasks like code review, with strict conditions to prevent the repository from accumulating low-quality or opaque artifacts.
• Any AI-assisted contribution must be backed by the contributor’s understanding and the ability to explain the code in PR descriptions and during reviews.
• There must be evidence that the code works through proper unit/integration tests, or via visual proof (pictures, videos, etc., as appropriate).
• Autonomously-submitted code via agentic AI tools is prohibited, ensuring maintainers can rely on human diligence.
• AI usage is strictly disallowed for issues labeled “good first issue,” which are designed to be tackled by humans learning the codebase.

This policy reflects a balanced stance that encourages leveraging AI while maintaining human accountability and code quality standards.

Community engagement: joining the conversation

The project actively invites community involvement. A Matrix room is available for informal chat about NixOS and to brainstorm ideas that could improve the tool. The invitation is explicit: this space is open to discuss features, share feedback, and work with contributors who want to help shape nixos-cli. If you have a command or capability you’d like to see implemented, you’re encouraged to join the Matrix room or file a GitHub issue to start the discussion.

Getting started: quick-start ideas for new users and contributors

If you’re new to nixos-cli, here are practical paths to begin their exploration:

• Install and try the wrapped vs unwrapped packages to understand how each behaves in your environment.
• Explore the command tree by listing top-level commands and experimenting with a few safe operations (for example, viewing available generations and option previews).
• Read the generated documentation on the website for common configuration settings and module documentation to get a sense of how the tool maps to NixOS concepts.
• Review the man pages generated with scdoc to get a Unix-style reference for daily usage.
• If you’re a developer, clone the repository, enter the nix development shell with nix develop .#, and start extending internal modules or adding new commands. Remember to follow the project’s guidelines about packaging, tests, and documentation.

Use cases: what nixos-cli helps you achieve

• Streamlined management: Replace scattered scripts with a unified tool that can manage NixOS installations across a range of devices.
• Safer upgrades: Use the generation manager to preview options and ensure smooth transitions between generations.
• Better discoverability: Through the option preview TUIs and in-depth documentation, users can understand available settings and their implications before applying changes.
• Consistent builds and releases: The Snix packaging approach and CI/CD ensure reproducibility, enabling teams to deploy with confidence.

Conclusion: a growing, thoughtful tool for NixOS administration

nixos-cli represents an ambitious attempt to unify NixOS management, balancing practical functionality with a thoughtful development and documentation plan. Its Go-based implementation, modular structure, and careful packaging strategy make it approachable for both users and contributors. By providing a unified CLI, generation previews, and a robust documentation pipeline, nixos-cli helps you navigate NixOS with less friction and more insight.

If you want to be part of this journey, consider joining the community discussions, trying out the build and test workflows, and contributing to the code, tests, or documentation. The project welcomes feedback, and the Matrix chat is a friendly place to start. Whether you’re a long-time NixOS user looking for a smoother workflow or a developer eager to contribute, nixos-cli offers a compelling path toward a standardized, high-quality toolset for managing NixOS installations.