https://github.com/nix-community/nh
Yet another nix cli helper
https://github.com/nix-community/nh
cli nix nix-flake nixos rust
Last synced: 5 months ago
JSON representation
Yet another nix cli helper
- Host: GitHub
- URL: https://github.com/nix-community/nh
- Owner: nix-community
- License: eupl-1.2
- Created: 2022-02-08T19:42:42.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2025-04-03T12:23:19.000Z (6 months ago)
- Last Synced: 2025-04-12T06:00:02.151Z (6 months ago)
- Topics: cli, nix, nix-flake, nixos, rust
- Language: Rust
- Homepage:
- Size: 605 KB
- Stars: 1,373
- Watchers: 7
- Forks: 50
- Open Issues: 31
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yaml
- License: LICENSE
Awesome Lists containing this project
- awesome-nix - nh - Better output for `nix`, `nixos-rebuild`, `home-manager` and nix-darwin CLI leveraging `dix` and `nix-output-monitor`. (Command-Line Tools / Discovery)
- best-of-nix - GitHub - 15% open · ⏱️ 07.09.2025) (Command-Line Tools)
README
nh
Because the name "yet-another-nix-helper" was too long to type...
## What does it do?
[nix-output-monitor]: https://github.com/maralorn/nix-output-monitor
[nvd]: https://khumba.net/projects/nvd
Nh is a modern helper utility that is a take at reimplementing some commands
from the NixOS ecosystem. We aim to provide more features and better ergonomics
than the existing commands.
We provide several subcommands, such as:
- `os`, which reimplements `nixos-rebuild`, with a tree of builds, diff and
confirmation.
- `home`, which reimplements `home-manager`.
- `darwin`, which reimplements `darwin-rebuild`
- `search`, a super-fast package searching tool (powered by a ElasticSearch
client).
- `clean`, my own take at cleaning GC roots from a NixOS system.
This wouldn't be possible without the programs that nh runs under the hood:
- Tree of builds with [nix-output-monitor].
- Visualization of the upgrade diff with [nvd].
- And of course, all the [crates](./Cargo.toml) we depend on.
## Installation
The latest, tagged version will is available in Nixpkgs as Nh stable. This
repository provides the latest development version of Nh, which you can get from
the flake outputs.
```sh
nix shell nixpkgs#nh # stable
nix shell github:viperML/nh # dev
```
### NixOS
We provide a NixOS module that integrates `nh clean` as a service. To enable it,
set the following configuration:
```nix
{ config, pkgs, ... }:
{
programs.nh = {
enable = true;
clean.enable = true;
clean.extraArgs = "--keep-since 4d --keep 3";
flake = "/home/user/my-nixos-config";
};
}
```
Nh supports both Flakes and classical NixOS configurations:
- For flakes, the command is `nh os switch /path/to/flake`
- For a classical configuration:
- `nh os switch -f ''`, or
- `nh os switch -f '' -- -I
nixos-config=/path/to/configuration.nix`
if using a different location than the default.
You might want to check `nh os --help` for other values and the defaults from
environment variables.
#### Specialisations support
Nh is capable of detecting which specialisation you are running, so it runs the
proper activation script. To do so, you need to give Nh some information of the
spec that is currently running by writing its name to `/etc/specialisation`. The
config would look like this:
```nix
{config, pkgs, ...}: {
specialisation."foo".configuration = {
environment.etc."specialisation".text = "foo";
# ..rest of config
};
specialisation."bar".configuration = {
environment.etc."specialisation".text = "bar";
# ..rest of config
};
}
```
#### Home-Manager
Home specialisations are read from `~/.local/share/home-manager/specialisation`.
The config would look like this:
```nix
{config, pkgs, ...}: {
specialisation."foo".configuration = {
xdg.dataFile."home-manager/specialisation".text = "foo";
# ..rest of config
};
specialisation."bar".configuration = {
xdg.dataFile."home-manager/specialisation".text = "bar";
# ..rest of config
};
}
```
## Status
[](https://deps.rs/repo/github/viperML/nh)
[](https://repology.org/project/unit/versions)
## Hacking
Just clone and `nix develop`. We also provide a `.envrc` for Direnv.