Install and upgrade the Nerlo CLI

The command-line client ships on PyPI as nerlo. This page covers getting it, keeping it current, and confirming which build you are actually running. For what each command does, see the CLI reference.

Before you start

You need Python 3.11, 3.12, or 3.13. The CLI's test suite runs on all three, on Linux, macOS, and Windows, so those nine combinations are the supported grid rather than an assumption.

Pick one installer and stay with it — mixing them is the single most common cause of "I upgraded and nothing changed", because each keeps its own copy and whichever one is first on your PATH wins.

Which version am I running?

nerlo version

It prints the tool name followed by the installed version. Note that version is a command here, not a flag — the double-dash option form does not exist and exits with a usage error.

What is the newest release?

Ask PyPI directly. This is one line and needs nothing installed but python3:

curl -s https://pypi.org/pypi/nerlo/json | python3 -c "import json,sys; print(json.load(sys.stdin)['info']['version'])"

If you already have pip, it can list every published release instead:

pip index versions nerlo

pip index prints a warning that it is an experimental command — that is expected, and the version list below it is still correct.

Compare that against what nerlo version told you. If they match, you are current and there is nothing to do.

Upgrade

pipx

The recommended path: pipx keeps the CLI in its own virtual environment, so an upgrade cannot disturb anything else on the machine.

pipx upgrade nerlo

If you do not have it yet:

pipx install nerlo

uv tool

uv tool upgrade nerlo

First install, and the listing that shows what uv is managing:

uv tool install nerlo

uv tool list --show-version-specifiers

uv tool upgrade --all moves every tool uv manages at once, which is usually what you want on a developer machine and never what you want in CI.

pip

pip install --upgrade nerlo

Use pip inside a virtual environment. On most current Linux distributions and on Homebrew Python, installing into the system interpreter is refused outright with an "externally-managed-environment" error — that is the platform protecting itself, not a fault in the package. pipx or uv is the answer there.

Confirm it moved

nerlo version

If the number did not change, you almost certainly have a second copy earlier on your PATH. which nerlo on Linux or macOS, and where nerlo on Windows, will show you which one is winning.

Pin the version in CI

A developer machine wants the newest build. A pipeline wants a build that does not change underneath it, so that a red build means your dependencies changed and never that your tooling did.

pipx install nerlo==<version>

uv tool install nerlo==<version>

pip install nerlo==<version>

Bump the pin deliberately, the same way you would any other build dependency.

Keeping the CI gate current

nerlo check is the reason to care about which version a build box is running. It reads the AI-tool configs a project already has, resolves every entry against the registry, and exits non-zero when policy is violated — so a flagged package fails the build whether or not anyone is watching a dashboard.

nerlo check . --fail-on unsafe

A stricter gate, once a team has submitted its dependency set:

nerlo check . --fail-on caution

--fail-on takes the wire tokens, which are not the words the registry displays. unsafe is what the site shows as Flagged, and caution is Caution. There is also any, which additionally fails on packages the registry has no verdict for.

Upgrading the CLI can change what the gate does, because scanner coverage and verdict handling both move with releases. Pin it, read the release notes, and bump on purpose — a gate that silently changes behaviour is worse than no gate, because the build stays green and nobody re-reads it.

The full exit-code contract, the machine-readable --json output, and worked GitHub Actions, GitLab CI, and Jenkins snippets are on the CLI reference. Handle exit code 3 — "could not determine" — explicitly. It is never a pass.

What the CLI sends

nerlo install sends anonymous install telemetry, and prints a one-time notice saying so the first time it does. Nothing else does: search, info, check, submit, rescan, and version send no telemetry at all.

Three fields go with it — a hashed installer token, the target platform you installed into, and the CLI version. The request is unauthenticated and carries no account credentials.

Opt out with either of these. The environment variable is the one to use in CI, and it works on the very first run, before any config file exists:

export NERLO_TELEMETRY=0

Or set it permanently in ~/.nerlo/config, the CLI's own settings file, one key=value per line:

mkdir -p ~/.nerlo && echo "telemetry=false" >> ~/.nerlo/config

The config value also accepts 0, no, and off. Set NERLO_HOME to relocate that directory if ~/.nerlo is not writable, which is common in a container.

See our privacy policy for what the registry retains.

Remove it

pipx uninstall nerlo

uv tool uninstall nerlo

pip uninstall nerlo

To go back to an earlier release, install that version over the current one:

pipx install nerlo==<version> --force

uv tool install nerlo==<version> --force