# Commands (/docs/commands)



This page covers every command exposed by the `snpm` CLI. For a terse flag/env-var matrix see [CLI Reference](/docs/cli-reference).

Global flags [#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 [#install]

```bash
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**

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

add [#add]

```bash
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](/docs/workspaces)).
* `--filter-prod <selector>` — production-only filter.

**Examples**

```bash
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 [#remove]

```bash
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**

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

run [#run]

```bash
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**

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

exec [#exec]

```bash
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**

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

init [#init]

```bash
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 [#dlx]

```bash
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**

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

upgrade [#upgrade]

```bash
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**

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

outdated [#outdated]

```bash
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 [#licenses]

```bash
snpm licenses [--json]
```

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

why [#why]

```bash
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 [#list]

```bash
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 [#link]

```bash
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 [#unlink]

```bash
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 [#pack]

```bash
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 [#publish]

```bash
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 [#rebuild]

```bash
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 [#audit]

```bash
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**

```bash
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 [#patch]

```bash
snpm patch <subcommand>
```

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

patch edit [#patch-edit]

```bash
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 [#patch-commit]

```bash
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 [#patch-remove]

```bash
snpm patch remove <package>
```

Deletes the patch file and removes the manifest entry.

patch list [#patch-list]

```bash
snpm patch list
```

Lists every patch declared in the current project.

clean [#clean]

```bash
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 [#store]

```bash
snpm store <subcommand>
```

Inspect or maintain the shared package store.

store status [#store-status]

```bash
snpm store status
```

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

store path [#store-path]

```bash
snpm store path
```

Prints just the store path (great for scripting).

store prune [#store-prune]

```bash
snpm store prune [--dry-run]
```

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

login [#login]

```bash
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**

```bash
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 [#logout]

```bash
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 [#config]

```bash
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 [#node]

```bash
snpm node <subcommand>
```

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

node install [#node-install]

```bash
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 [#node-use]

```bash
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 [#node-list--list-remote]

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

node current / which [#node-current--which]

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

node alias / unalias / default [#node-alias--unalias--default]

```bash
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 [#node-exec--run]

```bash
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 [#node-env]

```bash
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 [#completions]

```bash
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.