1---
2name: pnpm-cli-commands
3description: Essential pnpm commands for package management, running scripts, workspaces, publishing, and runtimes
4---
5 
6# pnpm CLI Commands
7 
8pnpm provides a comprehensive CLI. Commands resemble npm/yarn but with unique features.
9 
10## Installation Commands
11 
12```bash
13pnpm install            # install all deps (alias: pnpm i)
14pnpm add <pkg>          # production dependency
15pnpm add -D <pkg>       # devDependency       (also -d)
16pnpm add -O <pkg>       # optionalDependency  (also -o)
17pnpm add -E <pkg>       # exact version       (also -e)
18pnpm add <pkg>@<version>
19pnpm remove <pkg>       # aliases: rm, uninstall, un
20pnpm update             # alias: up
21pnpm update --latest    # ignore semver ranges (-L)
22pnpm update -i          # interactive
23```
24 
25### Clean / reproducible installs
26 
27```bash
28pnpm install --frozen-lockfile   # fail if lockfile would change (auto in CI)
29pnpm ci                          # clean install = pnpm clean + install --frozen-lockfile
30pnpm clean                       # remove node_modules in all workspace projects (alias: purge)
31pnpm clean --lockfile            # also delete pnpm-lock.yaml
32```
33 
34> Since v11, an integrity mismatch against the lockfile is a hard error (`ERR_PNPM_TARBALL_INTEGRITY`). Use `pnpm install --update-checksums` only after verifying the new bytes. In CI, pnpm also fails on lockfiles written by a newer pnpm major.
35 
36## Script Commands
37 
38```bash
39pnpm run <script>        # or just: pnpm <script>
40pnpm run build -- --watch
41pnpm run --if-present build
42pnpm set-script test "vitest run"   # add/update a scripts entry (alias: ss)
43pnpm exec <cmd>          # run a local binary, e.g. pnpm exec eslint .
44```
45 
46- **Hidden scripts:** names starting with `.` (e.g. `.helper`) can't be run directly, only called from other scripts.
47- **Built-in vs script conflict:** `clean`, `setup`, `deploy`, `rebuild` prefer a same-named `package.json` script. Force the built-in with `pnpm pm <name>` (e.g. `pnpm pm clean`).
48 
49### dlx / pnx — run without installing
50 
51```bash
52pnx create-vite my-app          # pnx == pnpm dlx == pnpx
53pnpm dlx degit user/repo dest
54pnx shx@catalog:                # catalog: protocol supported
55pnx --package=@scope/tool tool --help
56```
57 
58> `dlx`/`pnx` honor supply-chain settings (`minimumReleaseAge`, `trustPolicy`) and use the global virtual store by default in v11.
59 
60## Workspace Commands
61 
62```bash
63pnpm -r run <script>              # run in all packages (alias: --recursive)
64pnpm --filter <pattern> run <script>
65pnpm --filter "./packages/**" run build
66pnpm --filter "@myorg/*" run lint
67pnpm -r --parallel run dev
68```
69 
70### Filter patterns
71 
72```bash
73pnpm --filter <pkg-name> <cmd>      # by name (-F shorthand)
74pnpm --filter "./packages/core" test
75pnpm --filter "...@scope/app" build   # package + its dependencies
76pnpm --filter "@scope/core..." test   # package + its dependents
77pnpm --filter "...[origin/main]" build  # changed since git ref
78```
79 
80## Patches
81 
82```bash
83pnpm patch <pkg>@<version>     # opens an editable copy, prints a path
84pnpm patch-commit <path>       # writes patches/*.patch and records it
85pnpm patch-remove <pkg>@<version>
86```
87 
88## Linking local packages
89 
90```bash
91pnpm link <dir>          # link a path into this project's node_modules (path only!)
92pnpm add -g .            # register the current package's bins globally
93```
94 
95> Breaking in v11: `pnpm link` accepts **only relative/absolute paths** (no global store resolution, no `--global`, no bare `pnpm link`). Use `pnpm add -g .` to expose bins system-wide.
96 
97## Global packages (v11 isolated installs)
98 
99```bash
100pnpm add -g typescript prettier   # each gets its own isolated install dir
101pnpm add -g eslint,prettier       # comma = ONE shared install group
102pnpm add -g --allow-build=esbuild esbuild
103pnpm remove -g <pkg>
104pnpm list -g
105pnpm bin -g                       # show global bin dir ($PNPM_HOME/bin)
106```
107 
108> `pnpm install -g` (no args) is not supported. After upgrading to v11 run `pnpm setup` so `$PNPM_HOME/bin` is on PATH.
109 
110## Runtimes (Node/Deno/Bun)
111 
112```bash
113pnpm runtime set node 22 -g       # install & expose node (alias: rt)
114pnpm runtime set node lts -g
115pnpm runtime set deno 2 -g
116pnpm install --no-runtime         # skip installing devEngines.runtime entries
117```
118 
119## Store management
120 
121```bash
122pnpm store path        # store location (prints removed size after prune)
123pnpm store prune       # GC unreferenced packages (+ global virtual store links)
124pnpm store status
125```
126 
127## Inspection / registry
128 
129```bash
130pnpm list                 # alias: ls
131pnpm why <pkg>            # reverse-dependency tree (dedupes subtrees)
132pnpm why --find-by=<finder>   # custom finder from .pnpmfile.mjs
133pnpm outdated
134pnpm audit
135pnpm peers check          # report unmet/missing peers from the lockfile
136pnpm view <pkg> [field]   # registry metadata (aliases: info, show)
137pnpm whoami
138pnpm rebuild
139pnpm import               # create pnpm-lock.yaml from npm/yarn lockfile
140pnpm dedupe
141```
142 
143## Publishing
144 
145```bash
146pnpm pack
147pnpm publish -r --no-git-checks
148pnpm version patch|minor|major|2.0.0    # bump version, commit + tag (v11)
149pnpm version prerelease --preid beta
150pnpm deprecate <pkg>@<range> "message"
151pnpm dist-tag add <pkg>@<version> <tag>
152pnpm unpublish <pkg>@<version>          # discouraged; prefer deprecate
153pnpm sbom --sbom-format cyclonedx       # SBOM: cyclonedx (1.7) | spdx (2.3)
154pnpm stage publish ...                  # staged publishing (defer 2FA)
155```
156 
157## Maintenance & version management
158 
159```bash
160pnpm self-update [<version>]   # updates the packageManager pin, or installs globally
161pnpm with current install      # run a specific pnpm version for one command
162pnpm with 11.0.0 install
163pnpm approve-builds [--all]    # review dependency build scripts (writes allowBuilds)
164```
165 
166## Useful Flags
167 
168```bash
169pnpm install --ignore-scripts
170pnpm install --prefer-offline
171pnpm install --prod            # -P, omit devDependencies
172pnpm install --no-optional
173pnpm install --strict-peer-dependencies
174```
175 
176## Key Points
177 
178- `pnpm ci` = clean + frozen install; CI auto-enables frozen-lockfile.
179- `dlx`/`pnpx` are aliases of `pnx`; global installs are now isolated per package (comma-list to share).
180- `pnpm link` only takes paths; use `pnpm add -g .` for global bins.
181- Manage Node/Deno/Bun with `pnpm runtime set`; skip them at install with `--no-runtime`.
182- New publishing/registry commands: `version`, `view`, `whoami`, `deprecate`, `dist-tag`, `unpublish`, `sbom`, `stage`.
183 
184<!--
185Source references:
186- https://pnpm.io/cli/install
187- https://pnpm.io/cli/add
188- https://pnpm.io/cli/run
189- https://pnpm.io/filtering
190- https://pnpm.io/cli/link
191- https://pnpm.io/global-packages
192- https://pnpm.io/cli/runtime
193- https://pnpm.io/cli/version
194- https://pnpm.io/cli/with
195- https://pnpm.io/cli/sbom
196-->
197