How nem works

nem gives each project its own set of command-line tools and environment variables, scoped to that directory — plus an optional global set available everywhere. Nothing is installed into your system directories: tools live under nem’s own home and join your PATH only while they apply.

The nem.ver file

Each environment is described by a nem.ver file you keep in your project. It lists the packages and environment variables that should be active when you’re in that directory:

require (
	kubectl v1.34.1
)

require (
	helm v3.16.0 // indirect
)

env (
	KUBECONFIG=./kube/config
)

Packages you add yourself are direct entries. Their dependencies are pulled in automatically as indirect entries — listed in a separate require block and marked // indirect. You rarely edit the file by hand — nem use, nem unuse, and nem set-env keep it current, and nem tidy drops indirect packages nothing needs anymore. See the nem.ver format reference for the full syntax.

Project and global environments

When your shell enters a directory, nem finds the nearest nem.ver (in that directory or any ancestor) and makes exactly those tools available. Move into a different project and the toolset changes with it.

You can also manage tools globally with --global (-g), recorded in ~/.nem/nem.ver and available in every directory:

nem use --global ripgrep     # available everywhere
nem use kubectl@v1.34.1       # this project only

A project environment layers on top of the global one. See Global vs project scope.

Catalogs and manifests

nem doesn’t hardcode how to install anything. Each tool is described by a pkg.yaml manifest — a small file that says where to fetch the tool, how to verify it, and how to install it. A catalog is a collection of these manifests, one per package.

The public vi-dev/nem-catalog is enabled by default, so common tools work out of the box. Add your own catalog — from a local directory, a git repository, or an OCI registry — to use private or team-specific packages. See Working with catalogs and Authoring packages.

Install and PATH

nem fetches each package’s artifact, verifies its checksum (SHA-2 family; SHA-256 by default), and installs it under ~/.nem/ (override with NEM_HOME — see Configuration). Source-built packages run their build steps in a sandbox by default.

Tools reach your PATH through nem’s shell integration, which you enable once:

nem activate

nem activate adds a small managed block to your shell’s startup file (.bashrc, .zshrc, or config.fish). From then on, whenever you change directories nem updates your PATH and environment to match the active nem.ver, and restores them when you leave. It also enables tab completion.

In CI — or any non-interactive shell — skip the rc hook and wire up a single session with eval "$(nem shell-env)", or use the container image. See Shell integration.