Getting Started

nem makes your development environment appear the moment you enter a project directory. Declare the tools and environment variables a project needs in its nem.toml file, and nem handles the rest.

Installation

Install nem using the provided installation script:

curl -fsSL https://raw.githubusercontent.com/vi-dev/nem/main/install.sh | bash

By default, nem is installed to ~/.local/bin. Add this directory to your PATH if it isn’t already:

export PATH="$HOME/.local/bin:$PATH"

It’s possible to customize the installation using environment variables:

Examples:

To install unstable version:

curl -fsSL https://raw.githubusercontent.com/vi-dev/nem/main/install.sh | NEM_VERSION=unstable bash

Or install a specific version:

curl -fsSL https://raw.githubusercontent.com/vi-dev/nem/main/install.sh | NEM_VERSION=v0.1.0 bash

Prebuilt binaries for Linux and macOS are also attached to every GitHub release.

Update

nem is able to update itself:

nem self update                   # update to the latest stable release
nem self update --check           # check for updates without installing
nem self update --version v0.1.0  # update to a specific version

Quickstart

Try nem in a project directory:

nem activate      # hook nem into your shell (zsh, bash)
exec $SHELL

cd ~/code/my-project
nem use kubectl   # records the resolved version in nem.toml and installs it
kubectl version --client

kubectl is now on your PATH whenever you are in this directory.

Step by step

nem activate
exec $SHELL

nem use kubectl
nem use go@1.27.0

go version
kubectl version --client

nem sync

Everyday usage

Below are the most common commands you’ll use with nem.

For a complete list, run nem help.

How nem works

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

The manifest: nem.toml

Each environment is described by a nem.toml you keep in your project. It declares tools and environment variables:

[tools]
kubectl = '1.36.3'
terraform = '1.15.9'

[env]
AWS_PROFILE = 'dev'

You rarely edit it by hand — nem use and nem unuse maintain it. The global manifest lives at ~/.nem/nem.toml; target it with --global / -g.

The lockfile: nem.lock

Next to the manifest, nem writes nem.lock: the exact packages the manifest resolved to, including transitive dependencies, supported platforms, and a digest pinning each package’s catalog manifest. nem sync installs from the lockfile, and every download is verified against its digest before it is installed. Commit both files: nem.toml says what you want, nem.lock makes it reproducible.

If you edit nem.toml by hand, run nem lock to regenerate the lockfile and install.

The composed environment

Inside a project directory, nem composes the global environment with the project’s — the project’s declarations win. nem status shows the result; nem which <tool> shows where a specific tool resolves.

The composed environment reaches your shell in one of two ways:

• Shell hook — nem activate installs a hook (zsh, bash) that applies the environment automatically as you change directories.
• Explicitly — nem exec runs one command in the composed environment, and nem env prints the shell script that applies it (bash or zsh) — useful in CI and scripts.

Catalogs

Packages come from catalogs: usually OCI images that map package names and versions to downloadable, digest-pinned artifacts. On first run, nem configures the official catalog, ghcr.io/vi-dev/nem-catalog. nem catalog add registers others — including your own mirror inside an air-gapped network. nem search and nem info look across enabled catalogs.

Where things live

Everything nem installs stays under NEM_HOME (default ~/.nem): installed packages, catalog data, and the global manifest and lockfile. nem clean reclaims disk space; deleting the directory removes everything nem ever installed.

Next steps

To learn more about how to make the best of nem, check out our Guides and Reference.