CLI Reference

A condensed reference card. For prose, examples, and discussion see Commands.

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

install

snpm install [packages...]

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

add

snpm add <packages...>

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

remove

snpm remove <packages...>

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

run

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

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

exec

snpm exec <command> [args...]

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

dlx

snpm dlx <package> [args...]

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

upgrade

snpm upgrade [packages...]

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

outdated

snpm outdated

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

why

snpm why <package>

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

list

snpm list

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

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

snpm pack

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

publish

snpm publish

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

--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

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

clean

snpm clean

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

store

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

snpm login

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

logout

snpm logout

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

init

snpm init

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

config

snpm config

No flags. Prints resolved configuration.

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

snpm completions <shell>

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

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`)

--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

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

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

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

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

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

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

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`