The nx CLI¤
Nix is wonderful and intimidating in equal measure. The flake API is sharp, the language is alien on first contact, and the day-to-day tasks every developer expects from a package manager - install this, remove that, upgrade everything, undo what just broke - are buried under terminology like profiles, generations, and closures. The result is a steep cliff between "nix is installed" and "nix is useful".
nx is the bridge. It is a single, friendly command that wraps everything this tool ships - Nix profile management, scope composition, shell-profile injection, certificate handling, and the source-repo lifecycle - behind verbs you already know from apt, brew, and pip.
nx install httpie # add a package
nx remove httpie # remove it
nx upgrade # pull latest of everything
nx rollback # back out the last change
nx list # what's installed and where it came from
nx search ripgrep # find a package before installing
If you stopped reading here and only used those six commands, you would already be more productive with Nix than the official documentation lets on. But nx does more - it manages scopes (named bundles of related tools), runs health checks, exposes install provenance, and gives you a single entry point to re-provision the whole environment without remembering where you cloned the source repository six months ago. That is what the rest of this page covers.
The one mental model
nx writes plain text files in ~/.config/nix-env/ and asks Nix to make reality match. Every command is either editing the desired state (install, remove, scope add) or querying / maintaining the actual state (list, doctor, gc, rollback). There is no hidden database, no daemon, and no lock file you cannot read.
Command surface at a glance¤
| Verb | Closest analog | What it does |
|---|---|---|
nx search |
apt search |
Find a package in nixpkgs before installing |
nx install |
apt install / brew |
Add packages by name (validates against nixpkgs) |
nx remove |
apt remove |
Drop user-installed packages |
nx upgrade |
apt upgrade |
Pull latest nixpkgs and rebuild the profile |
nx list |
apt list --installed |
Show every package with its scope/origin annotation |
nx rollback |
(unique) | Revert to the previous Nix profile generation |
nx scope |
apt-get groups |
Manage named bundles of packages (curated or custom) |
nx overlay |
(unique) | Subscribe to team/org overlays by name |
nx pin |
(unique) | Lock nixpkgs to a specific commit for reproducibility |
nx profile |
(unique) | Manage shell-rc managed blocks (bash/zsh) |
nx setup |
(unique) | Re-run full provisioning (nix/setup.sh from anywhere) |
nx self |
(unique) | Update nx itself (no packages touched) |
nx doctor |
brew doctor |
Health checks against the live environment |
nx version |
apt-config |
Show install provenance, scopes, and live config |
nx prune |
(unique) | Remove orphaned nix profile entries |
nx gc / clean |
apt clean |
Garbage-collect old generations to reclaim disk |
Run nx help for the inline cheat sheet, or add --help (-h) to any command - nx upgrade --help, nx scope add --help - for its usage and options. A command given --help only prints help; it never runs.
Tab completion (bash, zsh, PowerShell)¤
You should never have to memorize the verbs in the table above. nx ships native tab completion for every shell it supports - installed automatically by nix/setup.sh into the managed shell-rc block, no extra wiring required.
| Shell | Source | Style |
|---|---|---|
| bash | .assets/config/shell_cfg/completions.bash |
Programmable completion (compgen -W ...) - completes verbs, subcommands, scope names from config.nix, and every setup flag |
| zsh | .assets/config/shell_cfg/completions.zsh |
Native _describe style - each subcommand suggestion includes a one-line description |
| PowerShell | .assets/config/pwsh_cfg/_aliases_nix.ps1 |
Register-ArgumentCompleter -Native - same coverage as bash, integrated with PSReadLine |
What you get out of the box:
nx <TAB><TAB> # all top-level commands
nx scope <TAB> # list show tree add edit remove
nx scope edit <TAB> # dynamic: only the scopes actually present in config.nix
nx setup --<TAB> # every scope flag + --omp-theme, --starship-theme, --latest, --all, ...
nx self update --<TAB> # --force
The PowerShell completer fires inside both the native pwsh REPL and VS Code's PowerShell terminal. The dynamic scope completion (for nx scope show|edit|remove) reads ~/.config/nix-env/config.nix directly, so it always reflects the current installation - including overlay scopes prefixed with local_.
Nothing to install
Completions live in the same managed shell-rc blocks that nix/setup.sh writes. If nx <TAB> doesn't fire, run nx profile doctor - a missing or duplicated block is the usual culprit, and nx profile regenerate fixes it without re-running setup.
Package management - the apt/brew layer¤
This is the part that erases the Nix learning cliff. Four verbs cover 90% of daily use.
nx install <pkg>...¤
nx install httpie
nx install ripgrep fd bat # install several at once
Each name is validated against nixpkgs before being added to packages.nix, so typos and non-existent packages fail fast - not after a 30-second nix profile upgrade. If a package is already provided by an enabled scope, nx tells you and skips the duplicate.
The package list lives in plain Nix at ~/.config/nix-env/packages.nix. You can read it, version-control it, or edit it by hand - but you almost never need to.
nx remove <pkg>...¤
nx remove httpie
nx uninstall httpie # alias
Removes packages from the user layer. If you ask to remove a package that's owned by a scope, nx refuses and points you at the right command (nx scope remove ...). This protects you from accidentally amputating a tool that something else depends on.
nx upgrade¤
nx upgrade
nx update # alias
The one command to bring packages up to date, like brew upgrade: it pulls the source repo, moves nixpkgs to the CI-validated revision, upgrades every package to it, and re-renders shell profiles. Under the hood it runs nix/setup.sh --skip-configure from the recorded repo; tool configuration (gh and git identity, per-scope installers, PowerShell modules) is left to nx setup.
nx upgrade --latest # nixpkgs-unstable HEAD instead - not validated by CI
If nx pin is set, the upgrade locks to the pinned revision. It never moves backwards: after --latest, plain upgrades wait until the validated revision catches up. If the network is unreachable, the existing lock is kept and the upgrade is reported as a warning rather than a failure. If the upgrade fails or is interrupted, the previous flake.lock is restored, so you stay on the last working revision.
Without the source repo on disk, nx upgrade still works: it upgrades packages in place to the revision synced last.
nx list¤
$ nx list
* bash-completion (base)
* git (base)
* httpie (extra)
* kubectl (k8s_base)
* ripgrep (shell)
* uv (python)
Every installed package, annotated with where it came from: (base) for the always-on baseline, (scope-name) for scope-owned packages, (extra) for nx install additions, (local) for personal scopes, (<overlay>/<scope>) for subscribed ones. No more guessing why a binary is on your PATH.
nx search <query>¤
nx search ripgrep
Thin wrapper over nix search nixpkgs --json with the output reformatted into a readable list (name + version + description). Use it before nx install to confirm the upstream package name.
Scopes - the curated bundles¤
A scope is a named set of packages that belongs together: python ships uv + prek + python3; k8s_dev ships flux, kustomize, trivy, kyverno, and friends. Scopes are how teams agree on a tooling baseline without writing a wiki page nobody reads.
See Customization for the full layering model. The day-to-day commands:
nx scope list # what's enabled
nx scope show k8s_dev # what packages does k8s_dev contain
nx scope tree # everything, expanded
nx scope add devtools httpie jq bat # create a personal scope
nx scope edit devtools # open in $EDITOR
nx scope remove devtools # drop the scope
Base vs overlay
Scopes shipped in this repository are read-only - nx scope edit shell will refuse and tell you to create a personal scope instead. Personal scopes get a local_ prefix on disk so they cannot collide with base scope names. Adding a scope re-runs nix profile upgrade automatically, so the new packages land immediately.
nx overlay¤
nx overlay
nx overlay browse github:my-org/dev-overlays # its overlays and what they are for
nx overlay add github:my-org/dev-overlays k8s # subscribe by name and apply
nx overlay remove k8s # unsubscribe
nx overlay update # fetch every subscription (same as nx upgrade)
Lists each subscription with its overlay, repository, ref and the commit it is on (or not fetched), then its scopes. Subscribed scopes are named <overlay>/<scope>; nx scope remove k8s/sofka opts out of one, marked (opted out), and nx scope add k8s/sofka brings it back. With no name, nx overlay add installs the only overlay or the one named default, and otherwise asks in a terminal. See Overlays.
Lifecycle - the unique entry point¤
This is where nx does things apt cannot. Three verbs manage the tool itself, not just packages.
nx setup [flags...]¤
nx setup # re-run with current scopes (nx upgrade + tool configuration)
nx setup --terraform --gcloud # add scopes to the existing config
nx setup --remove rice # drop a scope
Re-runs nix/setup.sh from anywhere - no need to remember where you cloned the repo. Every run pulls the repo and moves packages to the validated nixpkgs revision; use nx pin set to hold them on a revision instead. The lookup order is:
install.json:repo_pathif it points to a valid envy-nx checkout (respects forks and non-canonical clones).- Otherwise the canonical fallback
$HOME/source/repos/szymonos/envy-nx. If that location doesn't exist,nx setupclones it on demand - no prompt, no surprises. - If neither is reachable,
nx setupfails with a clear error.
When the recorded repo_path is stale (the directory was deleted or moved), nx setup falls back to the canonical location and prints a one-line notice so you know what happened. The new path is recorded in install.json automatically when nix/setup.sh exits - no manual cleanup.
nx self update [--force]¤
nx self update # git pull --ff-only
nx self update --force # fetch + reset --hard origin/<branch>
nx self path # print the recorded repo path
Updates nx itself: pulls the source repository and syncs the nx files into ~/.config/nix-env/. Packages, shell profiles and tool configs are left alone - nx upgrade applies those. Default is safe (--ff-only refuses to clobber local commits). --force resets to origin/<current-branch> for environments where the clone is treated as ephemeral. If the install was from a release tarball (no .git), nx self update offers to convert it to a git clone instead.
After an update, the in-shell nx_main function is invalidated so the next nx call re-sources the freshly-updated nx.sh - no shell restart needed.
nx version¤
$ nx version
envy-nx v1.2.0 (rfr/envy-setup)
Repo: /home/me/source/repos/szymonos/envy-nx
Installed: 2026-04-29 by me on Linux x86_64
Scopes: k8s_base k8s_dev python conda az terraform oh_my_posh shell pwsh rice
Mode: install
Status: success
Nix: Determinate Nix 3.18.1
Reads ~/.config/dev-env/install.json and prints the full provenance: tool version, repo path and branch, install timestamp, active scopes, last-run status. The single command that answers "what is actually deployed here?" - useful for fleet visibility, support tickets, and post-incident audits.
nx doctor¤
nx doctor
nx doctor --strict # warnings also exit non-zero (CI use)
nx doctor --json # machine-readable, no log file written
Read-only health checks that don't touch state. Failing or warning checks print a Fix: <command> hint indented under the check, so the common remediation (nx self sync, nx profile regenerate, nx upgrade, ...) is one read away. The full plain-text output is also written to ~/.config/dev-env/doctor.log (overwritten per run); the path is printed only when there are failures or warnings - a clean run is silent about it.
| Check | Verifies |
|---|---|
nix_available |
nix resolves on PATH and reports version ≥ 2.18 (older nix produces cryptic flake errors) |
flake_lock |
flake.lock exists and the nixpkgs node is valid |
nixpkgs_rev |
Locked nixpkgs matches the validated revision; surfaces a failed upgrade that rolled back |
env_dir_files |
flake.nix, nx.sh, nx_{pkg,scope,profile,lifecycle,doctor}.sh, profile_block.sh, config.nix present in ~/.config/nix-env/ |
install_record |
install.json exists and the last run succeeded |
scope_binaries |
Every binary declared by a scope's # bins: is found anywhere on $PATH |
scope_bins_in_profile |
Tighter: each # bins: binary must live under ~/.nix-profile/bin/ (proves nix provided it, not a system shadow) |
shell_profile |
Exactly one managed block in the invoking shell's rc (bash → .bashrc, zsh → .zshrc) |
managed_block_drift |
Both managed blocks (env:managed, nix:managed) in the invoking shell's rc match what nx profile regenerate would write today |
shell_config_files |
Every ~/.config/shell/<file> referenced by the rc resolves on disk |
cert_bundle |
Custom CA bundle present and VS Code env wired up |
vscode_server_env |
~/.vscode-server/server-env-setup includes nix PATH |
nix_profile |
nix-env entry exists in nix profile list |
nix_profile_link |
~/.nix-profile is a live symlink (not missing or dangling) |
overlay_subscriptions |
Every overlay subscription has its copy and its source: the clone, or the local folder (when any is set) |
version_skew |
Installed version matches the latest GitHub release (when gh is available) |
The nx doctor --strict form is what CI runs after every smoke test. Locally, run it whenever something feels off - it usually points at the broken edge in one line.
Maintenance - every operation is reversible¤
Nix's killer feature is profile generations. Every change creates a new generation; the previous one stays on disk until you explicitly clean it up. nx exposes that as everyday verbs.
nx rollback¤
nx rollback
Reverts to the previous profile generation. If nx upgrade brought in a broken kubectl, one command and a shell restart later, the old kubectl is back.
nx upgrade¤
nx upgrade # move to the validated nixpkgs revision
nx upgrade --latest # nixpkgs-unstable HEAD instead (unvalidated)
By default this moves to the revision recorded in nix/nixpkgs_rev.json - the one CI has built with every scope and installed end-to-end on Linux and macOS. That revision advances weekly, so an upgrade can lag real nixpkgs by a few days; that lag is the gate.
--latest opts out and takes nixpkgs-unstable HEAD, which nothing in this repo has built. If nix profile upgrade then fails, the previous flake.lock is restored so the machine stays on the revision that was working, and nx doctor reports the failed attempt.
An upgrade never moves you backwards: if the validated revision is older than what you already have (typical after --latest while the weekly bump is blocked), nx upgrade reports it and does nothing. Go back deliberately with nx pin set <rev>.
The validated revision reaches your machine with the rest of the repo: nx upgrade and nx setup pull it and move to it, nx self update syncs it without upgrading. Without the source repo, nx upgrade uses whatever was synced last.
nx pin¤
nx pin set # pin to whatever flake.lock currently has
nx pin set 1234abcd... # pin to a specific nixpkgs commit
nx pin show
nx pin remove # drop the pin (does not move the lock)
Coordinates a team or fleet on a single nixpkgs revision without shipping a flake.lock in the repo. A pin outranks both the validated revision and --latest, so nx upgrade honors it transparently. Useful for reproducible builds, cohort rollouts, freezing during a release window, or deliberately staying on an older revision.
nx prune¤
nx prune
Removes stale entries from nix profile list - leftovers from old experiments or aborted upgrades that aren't nix-env (the canonical profile this tool manages). Doesn't touch generations on disk; for that, use gc.
nx gc (nx clean)¤
nx gc
nix profile wipe-history + nix store gc. Deletes old profile generations and runs the Nix store garbage collector. Reclaims disk space - safe to run anytime, but rolls back the rollback target.
nx profile¤
nx profile doctor # check shell-rc managed blocks
nx profile regenerate # rewrite the blocks
nx profile uninstall # remove the blocks (keeps sourced files)
Manages the managed blocks that nix/setup.sh writes into ~/.bashrc and ~/.zshrc. See Architecture → Managed block pattern for the full design. The everyday case: if nx doctor reports a duplicate block, nx profile regenerate fixes it without re-running setup.
Why nx matters for this tool¤
A traditional take on Nix gives you nix profile add nixpkgs#httpie, nix flake update, nix profile rollback, and a stack of overlay terminology. It works, but it leaks the implementation into every command.
nx lets you forget that:
- No flake URLs to memorize.
nx install httpieis what you'd type withapt. - No "profile" vs "store" distinction at the surface.
nx upgradedoes what you mean, regardless of which Nix concept is involved underneath. - No hunting for the source repo.
nx setupfinds it, or clones the canonical location on demand. - Health, provenance, and rollback are first-class verbs.
nx doctor,nx version,nx rollback- each one is a single word, and each one answers a question you would otherwise google. - Imperative UX over declarative state. You change one thing imperatively (
nx install);nxupdates the declarative file (packages.nix) on your behalf and applies it. Best of both worlds.
The cost of this convenience is roughly 1200 lines of bash, a handful of unit tests, and a hard rule that the tool stays bash 3.2 / BSD-sed compatible so it works on a stock macOS shell. The cost is paid once. The benefit compounds every time a developer runs nx install instead of reading the Nix manual.
Reference¤
- Inline help:
nx help,nx <command> help - Source:
.assets/lib/nx.sh - Architecture context: Architecture, Customization
- Tests:
tests/bats/test_nx_commands.bats,tests/bats/test_nx_doctor.bats,tests/bats/test_nx_scope.bats