Commands

This page covers every command exposed by the snpm CLI. For a terse flag/env-var matrix see CLI Reference.

Global flags

These apply to any subcommand and can also be passed before the subcommand (snpm --frozen-lockfile install).

• -v, --verbose — verbose logging (also SNPM_VERBOSE=1).
• --frozen-lockfile — fail if the lockfile is missing or out of date.
• --no-frozen-lockfile — ignore the lockfile and re-resolve.
• --prefer-frozen-lockfile — reuse the lockfile when valid, otherwise re-resolve.

The lockfile flags propagate from the top-level call into any install-like subcommand (install, add, remove, upgrade, run, exec).

install

snpm install [packages...]

Install dependencies. With package arguments, behaves like snpm add for that list while still keeping the rest of the project in sync.

Flags

• --production — skip devDependencies.
• --frozen-lockfile (alias --immutable) — fail if the lockfile is missing or stale.
• --no-frozen-lockfile — ignore the lockfile and re-resolve.
• --prefer-frozen-lockfile — reuse lockfile when valid, otherwise re-resolve.
• --fix-lockfile — re-resolve drifted entries while preserving unchanged ones.
• -f, --force — ignore cached state and force a full install.
• -w, --workspace <name> — target a specific workspace project.

Examples

snpm install
snpm install react react-dom
snpm install --production --frozen-lockfile
snpm install --fix-lockfile
snpm install -w @acme/api

add

snpm add <packages...>

Add packages to dependencies (or devDependencies with -D).

Flags

• -D, --dev — save to devDependencies.
• -g, --global — install globally.
• -f, --force — ignore cached state.
• -w, --workspace <name> — target a specific workspace project.
• -r, --recursive — run in all workspace projects.
• --filter <selector> — workspace filter (see Workspaces).
• --filter-prod <selector> — production-only filter.

Examples

snpm add react react-dom
snpm add -D typescript
snpm add -g pnpm
snpm add react -w @acme/web
snpm add -r -D vitest
snpm add zod --filter "@acme/api"

remove

snpm remove <packages...>

Remove packages from the manifest and node_modules.

Flags

• -g, --global — remove a globally installed package.
• -r, --recursive — run in all workspace projects.
• --filter <selector> — workspace filter.
• --filter-prod <selector> — production-only filter.

Examples

snpm remove lodash
snpm remove -g create-react-app
snpm remove -r left-pad

run

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

Run a package.json script. Unknown top-level subcommands fall through to run (snpm build → snpm run build).

Flags

• -r, --recursive — run in all workspace projects.
• --filter <selector> — workspace filter.
• --filter-prod <selector> — production-only filter.
• --skip-install — skip the lazy install check that normally runs before scripts.

A lazy install runs automatically when node_modules is stale; use --skip-install to bypass.

Examples

snpm run build
snpm run test -- --watch
snpm run build -r
snpm run test --filter "api..."
snpm run lint --filter "[origin/main]"

exec

snpm exec <command> [args...]

Execute a command with node_modules/.bin on PATH.

Flags

• -c, --shell-mode — run through the shell (enables pipes, redirects, globs).
• -r, --recursive — run in all workspace projects.
• --filter <selector> — workspace filter.
• --filter-prod <selector> — production-only filter.
• --skip-install — skip the lazy install check.

Examples

snpm exec tsc --noEmit
snpm exec -c "eslint . | head -20"
snpm exec --recursive tsc --build

init

snpm init

Generate a fresh package.json with a normalized package name, 1.0.0 version, a packageManager pin for the current snpm version, and well-known field ordering.

dlx

snpm dlx <package> [args...]

Fetch and run a one-off package without persisting it to node_modules. Aliased to spx, snpx, and pnpx when invoked through those argv0s.

Flags

• --offline — run only from cache; fail if not cached.
• --prefer-offline — use cached version when available, fetch only if missing.

Examples

snpm dlx cowsay "hello"
snpm dlx create-vite my-app -- --template react-ts
spx cowsay "moo"

upgrade

snpm upgrade [packages...]

Upgrade dependencies within their declared semver ranges. Without arguments, deletes snpm-lock.yaml and re-resolves everything.

Flags

• --production — skip devDependencies.
• -f, --force — ignore cached state.
• -r, --recursive — run in all workspace projects.
• --filter <selector> — workspace filter.
• --filter-prod <selector> — production-only filter.

Examples

snpm upgrade
snpm upgrade react react-dom
snpm upgrade --production
snpm upgrade -r --filter "@acme/*"

outdated

snpm outdated

Report dependencies whose latest in-range version is newer than what is installed.

Flags

• --production — only check production dependencies.
• -r, --recursive — check every workspace project.
• --filter <selector> / --filter-prod <selector> — workspace filters.

licenses

snpm licenses [--json]

List the license of every installed package. The default table is human-readable; pass --json for programmatic consumption.

why

snpm why <package> [flags]

Explain why a package is in the install graph, printing reverse dependency paths from the root.

Flags

• --depth <N> — limit reverse dependency depth.
• --json — JSON output.
• -r, --recursive — run in all workspace projects.
• --filter <selector> / --filter-prod <selector> — workspace filters.

<package> accepts globs like babel-* and @types/*.

list

snpm list

Print the project's direct dependencies (or every globally installed package with -g).

Flags

• -g, --global — list global installs and the bin directory.
• -r, --recursive — list across workspace projects.
• --filter <selector> / --filter-prod <selector> — workspace filters.

link

snpm link [package]

• snpm link (no argument) — symlink the current package into the global link store.
• snpm link <name> — pull a previously linked package into the current project's node_modules.

unlink

snpm unlink [package]

Reverse of link. Without an argument, removes the current package from the global link store; with a name, removes the local link from the current project.

pack

snpm pack [flags]

Produce a publish tarball (<name>-<version>.tgz) in the current directory.

Flags

• --dry-run — show what would be packed without writing a tarball.
• --list — list every file included in the tarball.
• --json — emit pack inspection output as JSON.

Pack inspection surfaces findings — missing README, oversized files, files outside the package root — alongside the file manifest, so you can audit the tarball before publishing.

publish

snpm publish [flags]

Pack and publish the current package to its configured registry. Reads auth from .snpmrc / .npmrc / .pnpmrc and snpm login.

Flags

• --tag <tag> — distribution tag (defaults to latest).
• --access <public|restricted> — package access level for scoped packages.
• --otp <code> — one-time password for two-factor auth.
• --dry-run — perform packing and validation but skip the upload.
• --allow-risk <code> — allow a specific blocking pack-finding code for this publish only.
• -r, --recursive — publish every project in the workspace.
• --filter <selector> / --filter-prod <selector> — workspace filters.

The successful publish removes the local tarball it created. With --dry-run, the tarball is kept for inspection.

rebuild

snpm rebuild

Re-run install scripts for packages that already extracted, honoring the current allow-list (SNPM_ALLOW_SCRIPTS, workspace onlyBuiltDependencies). Run this after you change script policy or move a package onto the allow-list.

audit

snpm audit [packages...]

Scan the dependency graph for advisories from the registry's audit endpoint. Non-zero exit when vulnerabilities are reported.

Flags

• --audit-level <critical|high|moderate|low|info> — minimum severity to report.
• -P, --prod — production dependencies only.
• -D, --dev — devDependencies only.
• --format <table|json|sarif> — output format. SARIF integrates with GitHub/GitLab security tabs.
• --fix — try to upgrade vulnerable packages.
• --ignore-cve <id> (repeatable) — suppress a specific CVE.
• --ignore-ghsa <id> (repeatable) — suppress a specific GHSA.
• --ignore-unfixable — skip advisories with no available fix.
• --ignore-registry-errors — exit 0 if the registry's audit endpoint fails.

Examples

snpm audit
snpm audit --audit-level high
snpm audit --format sarif > audit.sarif
snpm audit --fix
snpm audit --ignore-cve CVE-2025-12345 --ignore-unfixable

patch

snpm patch <subcommand>

Persist edits to installed packages as a unified diff applied on every install.

patch edit

snpm patch edit <package[@version]>

Alias: snpm patch start. Copies the installed package into a temp working directory and emits a .snpm_patch_session marker.

patch commit

snpm patch commit <path>

Diffs the modified directory against the original and writes the patch to patches/<package>@<version>.patch. Updates the manifest's snpm.patched_dependencies map (pnpm.patched_dependencies is also recognized for compatibility).

Scoped names use + in the patch filename — @babel/core becomes +babel+core@7.0.0.patch.

patch remove

snpm patch remove <package>

Deletes the patch file and removes the manifest entry.

patch list

snpm patch list

Lists every patch declared in the current project.

clean

snpm clean [flags]

Reclaim disk space by removing cached packages, metadata, and (optionally) global installs.

Flags

• -y, --yes — skip the confirmation prompt.
• --dry-run — preview what would be removed.
• --packages — only clean the cached package store.
• --metadata — only clean registry metadata.
• --global — also clean global installs and binaries.
• --all — clean everything.

store

snpm store <subcommand>

Inspect or maintain the shared package store.

store status

snpm store status

Shows the store path and a breakdown of package and metadata counts/sizes.

store path

snpm store path

Prints just the store path (great for scripting).

store prune

snpm store prune [--dry-run]

Remove incomplete or orphaned packages from the store. --dry-run lists candidates without deleting.

login

snpm login [flags]

Authenticate with a registry. The web flow is the default — snpm login opens a browser, completes OAuth, and saves the resulting Bearer token to ~/.snpmrc.

Flags

• --registry <url> — registry URL (defaults to the configured default; URL is normalized).
• --scope <scope> — associate credentials with a scope (e.g. @myorg).

Examples

snpm login
snpm login --registry https://npm.mycompany.com
snpm login --scope @myorg --registry https://npm.mycompany.com

Tokens can also be set via environment variables (SNPM_AUTH_TOKEN, NODE_AUTH_TOKEN, NPM_TOKEN) or .snpmrc (_authToken, _auth).

logout

snpm logout [flags]

Remove stored registry credentials.

Flags

• --registry <url> — registry URL to clear (defaults to the current default).
• --scope <scope> — clear credentials for a specific scope.

config

snpm config

Print the resolved configuration: cache and data paths, registry/auth, install settings (hoisting, link backend, local-virtual-store packages, strict peers, frozen-lockfile default, min package age, registry concurrency, always-auth), allow-scripts list, and logging status. Useful as the first step when something looks off.

node

snpm node <subcommand>

A built-in nvm-style Node.js version manager.

node install

snpm node install [version] [--lts] [--default]

Download and install a Node.js version. Accepts 20, 20.10.0, v20, ^20, lts, lts/iron, or latest. --lts selects the newest LTS. --default activates the install as the new default.

node use

snpm node use [version] [--lts] [--default] [--install] [--silent]

Activate a Node version for the current shell. With no argument, snpm reads .node-version, .nvmrc, or engines.node from the project tree. --install downloads the version on demand.

node list / list-remote

snpm node list           # installed versions (alias: ls)
snpm node ls-remote      # versions available from nodejs.org (alias: remote)

node current / which

snpm node current        # currently active version
snpm node which 20       # absolute path to a binary for a version

node alias / unalias / default

snpm node alias work 20            # create an alias
snpm node alias                    # list aliases
snpm node unalias work
snpm node default 20               # shortcut for `node alias default 20`

node exec / run

snpm node exec 20 -- node --version           # one-off command under a version
snpm node run 20 test                         # run a package.json script with that version

node env

snpm node env --shell zsh

Prints shell integration that auto-switches Node versions based on the closest .node-version / .nvmrc / engines.node. Pipe the output into your shell init file (source <(snpm node env --shell zsh)).

completions

snpm completions <shell>

Generate shell completions. Supported: bash, zsh, fish, powershell, elvish. Hidden from --help because it is an internal helper; the npm package also bundles completions where possible.