# CLI Reference (/docs/cli-reference)



A condensed reference card. For prose, examples, and discussion see [Commands](/docs/commands).

Global flags [#global-flags]

| Flag                       | Description                                                                      |
| -------------------------- | -------------------------------------------------------------------------------- |
| `-v, --verbose`            | Enable verbose logging (also `SNPM_VERBOSE=1`)                                   |
| `--frozen-lockfile`        | Fail if lockfile is missing/out of date (propagates to install-like subcommands) |
| `--no-frozen-lockfile`     | Ignore lockfile, re-resolve                                                      |
| `--prefer-frozen-lockfile` | Use lockfile when valid, otherwise re-resolve                                    |

Commands [#commands]

install [#install]

`snpm install [packages...]`

`--production`, `--frozen-lockfile`/`--immutable`, `--no-frozen-lockfile`, `--prefer-frozen-lockfile`, `--fix-lockfile`, `-f/--force`, `-w/--workspace <name>`.

add [#add]

`snpm add <packages...>`

`-D/--dev`, `-g/--global`, `-f/--force`, `-w/--workspace <name>`, `-r/--recursive`, `--filter <selector>`, `--filter-prod <selector>`.

remove [#remove]

`snpm remove <packages...>`

`-g/--global`, `-r/--recursive`, `--filter <selector>`, `--filter-prod <selector>`.

run [#run]

`snpm run <script> [-- args...]`

`-r/--recursive`, `--filter <selector>`, `--filter-prod <selector>`, `--skip-install`. Unknown subcommands fall through to `run`.

exec [#exec]

`snpm exec <command> [args...]`

`-c/--shell-mode`, `-r/--recursive`, `--filter <selector>`, `--filter-prod <selector>`, `--skip-install`.

dlx [#dlx]

`snpm dlx <package> [args...]`

`--offline`, `--prefer-offline`. Aliases when invoked as `spx`, `snpx`, `pnpx`.

upgrade [#upgrade]

`snpm upgrade [packages...]`

`--production`, `-f/--force`, `-r/--recursive`, `--filter <selector>`, `--filter-prod <selector>`. With no packages, deletes the lockfile and re-resolves.

outdated [#outdated]

`snpm outdated`

`--production`, `-r/--recursive`, `--filter <selector>`, `--filter-prod <selector>`.

licenses [#licenses]

`snpm licenses`

`--json`.

why [#why]

`snpm why <package>`

`--depth <N>`, `--json`, `-r/--recursive`, `--filter <selector>`, `--filter-prod <selector>`. Supports glob patterns.

list [#list]

`snpm list`

`-g/--global`, `-r/--recursive`, `--filter <selector>`, `--filter-prod <selector>`.

link / unlink [#link--unlink]

`snpm link [package]` · `snpm unlink [package]`

No flags. Without a package name, operates on the current project against the global link store.

pack [#pack]

`snpm pack`

`--dry-run`, `--list`, `--json`.

publish [#publish]

`snpm publish`

`--tag <tag>` (default `latest`), `--access <public|restricted>`, `--otp <code>`, `--dry-run`, `--allow-risk <code>`, `-r/--recursive`, `--filter <selector>`, `--filter-prod <selector>`.

rebuild [#rebuild]

`snpm rebuild`

No flags.

audit [#audit]

`snpm audit [packages...]`

`--audit-level <level>`, `-P/--prod`, `-D/--dev`, `--format <table|json|sarif>`, `--fix`, `--ignore-cve <id>` (repeatable), `--ignore-ghsa <id>` (repeatable), `--ignore-unfixable`, `--ignore-registry-errors`.

patch [#patch]

`snpm patch edit <pkg[@version]>` (alias `patch start`) · `snpm patch commit <path>` · `snpm patch remove <pkg>` · `snpm patch list`.

clean [#clean]

`snpm clean`

`-y/--yes`, `--dry-run`, `--packages`, `--metadata`, `--global`, `--all`.

store [#store]

`snpm store status` · `snpm store path` · `snpm store prune [--dry-run]`.

login [#login]

`snpm login`

`--registry <url>`, `--scope <scope>`. Default flow is web-based; the resulting Bearer token is saved to `~/.snpmrc`.

logout [#logout]

`snpm logout`

`--registry <url>`, `--scope <scope>`.

init [#init]

`snpm init`

No flags. Generates `package.json` with `packageManager` pinned to the running `snpm` version.

config [#config]

`snpm config`

No flags. Prints resolved configuration.

node [#node]

`snpm node <subcommand>` — full nvm-style version manager.

Subcommands: `install [version] [--lts] [--default]`, `uninstall <version>`, `use [version] [--lts] [--default] [--install] [--silent]`, `list` (alias `ls`), `ls-remote` (aliases `list-remote`, `remote`), `current`, `which <version>`, `alias <name> [version]`, `unalias <name>`, `default <version>`, `exec <version> -- <cmd>`, `run <version> <script>`, `env [--shell <name>]`.

completions [#completions]

`snpm completions <shell>`

Hidden helper. Supported shells: `bash`, `zsh`, `fish`, `powershell`, `elvish`.

Multicall aliases [#multicall-aliases]

snpm rewrites argv0 when invoked as a known alias:

| argv0                 | Behaves as |
| --------------------- | ---------- |
| `spx`, `snpx`, `pnpx` | `snpm dlx` |
| `snpr`                | `snpm run` |

Workspace selectors (--filter / --filter-prod) [#workspace-selectors---filter----filter-prod]

`--filter` selects projects against the workspace dependency graph. The same grammar is used by every workspace-aware command (`add`, `remove`, `run`, `exec`, `upgrade`, `outdated`, `list`, `why`, `publish`).

| Pattern                                 | Effect                                                          |
| --------------------------------------- | --------------------------------------------------------------- |
| `pkg-name`                              | Exact project name                                              |
| `@scope/*`, `foo-?`                     | Glob over project names                                         |
| `./packages/api`, `../lib`, `/abs/path` | Path-based match (project rooted at this path)                  |
| `pkg...`                                | The package and everything it depends on                        |
| `...pkg`                                | The package and everything that depends on it                   |
| `^pkg...` / `pkg^...`                   | Same as above, but exclude the seed (graph operators only)      |
| `[<git-ref>]`                           | Projects with files changed since `<git-ref>` (uses `git diff`) |
| `!pkg`                                  | Exclude (combine with positive selectors)                       |

`--filter-prod` accepts the same grammar but restricts dependency/dependent walks to production dependencies only.

Environment variables [#environment-variables]

Directories [#directories]

| Variable    | Purpose                                               |
| ----------- | ----------------------------------------------------- |
| `SNPM_HOME` | Sets `cache=$SNPM_HOME/cache`, `data=$SNPM_HOME/data` |

Without `SNPM_HOME`, platform defaults are used:

* macOS: cache `~/Library/Caches/snpm`, data `~/Library/Application Support/io.snpm.snpm`
* Linux: cache `~/.cache/snpm`, data `~/.local/share/snpm`
* Windows: cache `%LOCALAPPDATA%\snpm\snpm\cache`, data `%LOCALAPPDATA%\snpm\snpm\data`

Install behavior [#install-behavior]

| Variable                                         | Default                           | Values                                        |
| ------------------------------------------------ | --------------------------------- | --------------------------------------------- |
| `SNPM_HOIST`                                     | `single-version`                  | `none`, `single-version`, `all`               |
| `SNPM_LINK_BACKEND`                              | `auto`                            | `auto`, `hardlink`, `symlink`, `copy`         |
| `SNPM_STRICT_PEERS`                              | `false`                           | truthy                                        |
| `SNPM_FROZEN_LOCKFILE`                           | `false`                           | truthy                                        |
| `SNPM_REGISTRY_CONCURRENCY`                      | `128`                             | integer > 0                                   |
| `SNPM_DISABLE_GLOBAL_VIRTUAL_STORE_FOR_PACKAGES` | `next,nuxt,vite,vitepress,parcel` | Comma-separated names; `[]` disables the list |

Truthy values: `1`, `true`, `yes`, `y`, `on`.

Registry & auth [#registry--auth]

| Variable                                                       | Description                                   |
| -------------------------------------------------------------- | --------------------------------------------- |
| `NPM_CONFIG_REGISTRY` / `npm_config_registry`                  | Default registry URL                          |
| `PNPM_CONFIG_REGISTRY` / `pnpm_config_registry`                | Same, pnpm prefix                             |
| `SNPM_CONFIG_REGISTRY` / `snpm_config_registry`                | Same, snpm prefix (highest precedence)        |
| `SNPM_AUTH_TOKEN`, `NODE_AUTH_TOKEN`, `NPM_TOKEN`              | Bearer token for default registry             |
| `NPM_CONFIG__AUTH` / `PNPM_CONFIG__AUTH` / `SNPM_CONFIG__AUTH` | Base64 Basic credentials for default registry |
| `NPM_CONFIG_ALWAYS_AUTH` / `SNPM_ALWAYS_AUTH`                  | Force auth on every request (truthy)          |

snpm prefers `SNPM_*`, then `PNPM_*`, then `NPM_*` for the registry/auth variables that have all three forms.

Security [#security]

| Variable                          | Default | Description                                             |
| --------------------------------- | ------- | ------------------------------------------------------- |
| `SNPM_ALLOW_SCRIPTS`              | (empty) | Comma-separated packages allowed to run install scripts |
| `SNPM_MIN_PACKAGE_AGE_DAYS`       | (none)  | Ignore versions published within N days                 |
| `SNPM_MIN_PACKAGE_CACHE_AGE_DAYS` | `7`     | Re-fetch metadata older than N days                     |

Logging [#logging]

| Variable        | Default | Description                                                        |
| --------------- | ------- | ------------------------------------------------------------------ |
| `SNPM_VERBOSE`  | `false` | Enable verbose output (also `-v/--verbose`)                        |
| `SNPM_LOG_FILE` | (unset) | Custom log file path (defaults to `.snpm.log` in cwd when verbose) |

Exit codes [#exit-codes]

| Code | Meaning                                                                                                       |
| ---- | ------------------------------------------------------------------------------------------------------------- |
| `0`  | Success                                                                                                       |
| `1`  | Any error: install failure, lockfile drift in frozen mode, audit found vulnerabilities, publish refused, etc. |

`snpm audit` exits `1` when vulnerabilities are present unless `--ignore-registry-errors` was set and the registry itself failed.

Comparison with npm [#comparison-with-npm]

| npm                            | snpm                                          |
| ------------------------------ | --------------------------------------------- |
| `npm install`                  | `snpm install`                                |
| `npm install <pkg>`            | `snpm add <pkg>`                              |
| `npm install <pkg> --save-dev` | `snpm add -D <pkg>`                           |
| `npm install -g <pkg>`         | `snpm add -g <pkg>`                           |
| `npm uninstall <pkg>`          | `snpm remove <pkg>`                           |
| `npm update`                   | `snpm upgrade`                                |
| `npm outdated`                 | `snpm outdated`                               |
| `npm run <script>`             | `snpm run <script>` (or `snpm <script>`)      |
| `npx <pkg>`                    | `snpm dlx <pkg>` (or `spx <pkg>`)             |
| `npm init`                     | `snpm init`                                   |
| `npm login` / `npm logout`     | `snpm login` / `snpm logout`                  |
| `npm pack` / `npm publish`     | `snpm pack` / `snpm publish`                  |
| `npm audit` / `npm audit fix`  | `snpm audit` / `snpm audit --fix`             |
| `npm explain <pkg>`            | `snpm why <pkg>`                              |
| `npm ls -g`                    | `snpm list -g`                                |
| `npm link` / `npm unlink`      | `snpm link` / `snpm unlink`                   |
| `npm rebuild`                  | `snpm rebuild`                                |
| `npm cache clean --force`      | `snpm clean` (interactive) or `snpm clean -y` |