hnm — HackerOS Nix Manager

Overview #

HNM gives you access to the entire nixpkgs repository (~100 000 packages) without having to manage Nix flakes, NixOS modules, or configuration.nix. It works identically to how Flox uses Nix under the hood — a dedicated nix-env profile at ~/.hnm/profile.

Quickstart #

# Search for a package
$ hnm search ripgrep

# Install packages
$ hnm install ripgrep bat htop

# Show information about a package
$ hnm info ripgrep

# List packages installed via hnm
$ hnm list -i

# Browse the full local package catalog
$ hnm list

# Update everything
$ hnm update

# Remove a package (asks to confirm unless --force)
$ hnm remove htop

# Check Nix installation
$ hnm check

# Run full diagnostics
$ hnm doctor

Command Reference #

Package commands

System commands

Command aliases

Search & Install #

Searching

hnm search looks up the local index (pkgdb.tsv, built by hnm update) and displays results in a formatted table, including descriptions. Installed packages are marked with a ✓.

# Basic search
$ hnm search ripgrep

# JSON output (useful for scripting)
$ hnm search ripgrep --json

Installing

hnm install resolves the package in nixpkgs, installs it into ~/.hnm/profile via nix-env, and records it — including its description — in the HNM state file. Multiple packages can be installed in one command.

# Install a single package
$ hnm install ripgrep

# Install multiple packages at once
$ hnm install ripgrep bat htop neovim fd

# Install without the PATH-activation hint at the end
$ hnm install ripgrep --no-env

--no-env is meant for scripted or non-interactive installs where the caller already manages PATH itself. It only suppresses the printed hint — the package is still installed into the HNM profile exactly the same way.

Updating Packages #

hnm update runs three steps: refresh the nixpkgs channel (nix-channel --update), rebuild the local search index (nix-env -qaP --description), then upgrade installed, non-pinned packages one at a time (nix-env -uA).

# Update everything
$ hnm update

# Update specific packages only
$ hnm update ripgrep bat

After a successful update, if config.hk has max_generations set (default 10), older generations beyond that count are pruned with nix-env --delete-generations. If auto_gc is enabled, hnm gc runs automatically afterwards. See Configuration.

Pinning #

Pinning records a specific version in the HNM state file and marks the package so it's protected from both accidental upgrades and accidental removal.

# Pin at the currently installed version
$ hnm pin ripgrep

# Pin at a specific version
$ hnm pin ripgrep 14.0.0

# Remove the pin
$ hnm unpin ripgrep

Pinned packages appear in hnm list -i with a [pinned: x.x.x] annotation.

Generations & Rollback #

Every install, remove, or upgrade in nix-env creates a new generation — a snapshot of the profile state. HNM exposes this through hnm rollback, tracks the current generation number in state.json, and (if max_generations is configured) prunes old ones automatically.

# Roll back to the previous generation
$ hnm rollback

# Roll back to a specific generation number
$ hnm rollback 3

# The rollback command shows available generations first:
  gen    1   2024-12-01
  gen    2   2025-01-15
  gen    3   2025-03-22  ← current

Progress & Logs #

HNM uses a combined progress display: scrolling log lines above a live progress bar with a spinner, percentage, and current action label. Stderr from Nix commands is shown inline as error lines.

The spinner cycles through / → - → \ → |. Log lines scroll above the bar and are preserved in the terminal history once the operation completes.

Color Scheme #

Doctor #

hnm doctor runs a full health check of your HNM and Nix setup. It checks for required binaries, Nix channels, the HNM profile directory, the Nix store, state and config files, PATH configuration, and — since v0.2 — whether state.json has drifted from what nix-env actually has installed.

$ hnm doctor

  ▸ HNM Doctor — system diagnostics
  ──────────────────────────────────────────────────
  ✓ nix             nix (Nix) 2.18.4
  ✓ nix-env         nix-env (Nix) 2.18.4
  ✓ nix-channel     nix-channel (Nix) 2.18.4
  ✓ nix-store       nix-store (Nix) 2.18.4

  ✓ channels        nixpkgs https://nixos.org/channels/nixpkgs-unstable
  ✓ profile         /home/user/.hnm/profile
  ✓ /nix/store      exists  (4.2G)

  ✓ state           12 package(s) tracked
  ✓ config          channel = https://nixos.org/channels/nixpkgs-unstable

  ✓ PATH            contains .nix-profile

  ✓ all checks passed — HNM is healthy

If state and the real profile disagree (e.g. after a manual nix-env call, or before hnm list -i has had a chance to resync), doctor reports it instead of silently passing:

  ⚠ state drift: 1 untracked in profile, 0 stale in state.json  →  run `hnm list -i`

Environment #

HNM packages are installed into ~/.hnm/profile/bin. To use them in your shell, add the profile to your PATH — either manually, or let hnm env do it for you.

# Print the snippet to add to your shell rc (default, non-destructive)
$ hnm env activate

# Actually patch ~/.bashrc, ~/.zshrc, ~/.profile automatically
$ hnm env activate --yes

# Check current status, including which rc files are already patched
$ hnm env status

# Print removal instructions (default), or apply them automatically
$ hnm env deactivate
$ hnm env deactivate --yes

What gets added, if you don't use --yes and prefer to paste it yourself:

# HNM — HackerOS Nix Manager
export PATH="$HOME/.hnm/profile/bin:$HOME/.nix-profile/bin:$PATH"
[ -f ~/.nix-profile/etc/profile.d/nix.sh ] && \
    . ~/.nix-profile/etc/profile.d/nix.sh

Garbage Collection #

Nix keeps every version of every package in /nix/store. Over time this can grow large. Run hnm gc to collect unreachable store paths, or set auto_gc = true in config.hk to have hnm remove and hnm update do it for you automatically.

$ hnm gc

  ▸ Nix garbage collection
  ────────────────────────────────
       store size before   4.2G

  │ nix-store --gc
  │ finding garbage collector roots...
  │ deleting garbage...
  │ deleting '/nix/store/old-path-xyz'
  │ ...
  /  [████████████████████████████████████████]  100%  ✓ garbage collection complete

       store size after    2.1G
  ✓ done

Clean Cache #

hnm clean removes HNM's own download cache and the Nix evaluation cache. It does not touch the Nix store — use hnm gc for that.

$ hnm clean

  ✓ removed ~/.cache/hnm   (128 MB)
  ✓ removed nix eval cache  (44 MB)

  ✓ freed 172 MB
  To free Nix store space, run:  hnm gc

Auto Nix Bootstrap #

Every command that requires Nix (install, remove, search, update, gc, etc.) checks whether Nix is present before running. If Nix is missing, HNM automatically runs hnm unpack to bootstrap it — no manual action required.

# Manually bootstrap Nix
$ hnm unpack

# This runs:
#   sh <(curl -L https://nixos.org/nix/install) --no-daemon
#   . ~/.nix-profile/etc/profile.d/nix.sh
#   nix-channel --add https://nixos.org/channels/nixpkgs-unstable nixpkgs
#   nix-channel --update
#   (patch ~/.bashrc, ~/.zshrc, ~/.profile)

Configuration #

As of v0.2, HNM stores its configuration as .hk — HackerOS's own configuration format — instead of TOML: ~/.config/hnm/config.hk. Parsing and serialization are handled by the hk-parser crate. The full format spec lives at tools-docs/hk.html. The file is created automatically on first run with sensible defaults.

# ~/.config/hnm/config.hk
! HNM configuration — HackerOS Nix Manager
! format: https://hackeros-linux-system.github.io/HackerOS-Website/tools-docs/hk.html

[hnm]
-> nix_channel     => "https://nixos.org/channels/nixpkgs-unstable"
-> profile_dir     => "/home/user/.hnm/profile"
-> auto_gc         => false
-> max_generations => 10

State File & Drift #

HNM tracks installed packages in ~/.local/share/hnm/state.json. This is separate from the Nix profile itself and records HNM-specific metadata such as install timestamps, descriptions, pins, and the current generation number.

{
  "installed": {
    "ripgrep": {
      "name":         "ripgrep",
      "version":      "14.1.1",
      "attr_path":    "nixpkgs.ripgrep",
      "installed_at": "2025-04-17T10:32:00Z",
      "pinned":       null,
      "description": "Fast grep alternative written in Rust"
    }
  },
  "generation":   4,
  "last_update":  "2025-04-17T10:35:00Z"
}

Why state can drift, and how HNM handles it

Because state.json is separate bookkeeping from nix-env's own profile, the two can disagree — for example if a package is installed or removed by hand with nix-env directly, or after hnm rollback switches which generation is active (that changes what's actually installed without touching state.json on its own).

• hnm list -i reconciles state against the live profile before printing, adding anything untracked and dropping anything stale.
• hnm rollback runs the same reconciliation immediately after switching generations, and updates the tracked generation number.
• hnm doctor reports drift as a warning (without silently fixing it), so you know reconciliation happened, or is needed.

HNM vs Flox #

Changelog #