CLI documentation update from CI
npm CLI robot committed
May 27, 2026 at 20:47 UTC
88e8037b79d80d0a5af08b50605ce0d8ac0da32c
18 files changed
+499
-11
cli-cache.json
+1
-1
@@ -2,5 +2,5 @@
2
"v8": "aa8fff11cdab94fff1a2160ee5241f5f4632e96b",
3
"v9": "64763a341e7aa5b456e696f956759bf9b3440dc1",
4
"v10": "189ba136a75c773927a5cb8922e6b00c71814d35",
5
- "v11": "33aebaa58541ac0af3882cc0b56f09b1b676740a"
5
+ "v11": "da63c79be758fd9d3faa9f5edf962219c805c579"
6
}
\ No newline at end of file
content/cli/v11/commands/npm-approve-scripts.mdx
new
+125
@@ -0,0 +1,125 @@
1
+---
2
+title: npm-approve-scripts
3
+section: 1
4
+description: Approve install scripts for specific dependencies
5
+github_repo: npm/cli
6
+github_branch: latest
7
+github_path: docs/lib/content/commands/npm-approve-scripts.md
8
+redirect_from:
9
+ - /cli-commands/approve-scripts
10
+ - /cli-commands/npm-approve-scripts
11
+ - /cli-documentation/approve-scripts
12
+ - /cli-documentation/cli-commands/approve-scripts
13
+ - /cli-documentation/cli-commands/npm-approve-scripts
14
+ - /cli-documentation/commands/approve-scripts
15
+ - /cli-documentation/commands/npm-approve-scripts
16
+ - /cli-documentation/npm-approve-scripts
17
+ - /cli-documentation/v11/approve-scripts
18
+ - /cli-documentation/v11/cli-commands/approve-scripts
19
+ - /cli-documentation/v11/cli-commands/npm-approve-scripts
20
+ - /cli-documentation/v11/commands/approve-scripts
21
+ - /cli-documentation/v11/commands/npm-approve-scripts
22
+ - /cli-documentation/v11/npm-approve-scripts
23
+ - /cli/approve-scripts
24
+ - /cli/cli-commands/approve-scripts
25
+ - /cli/cli-commands/npm-approve-scripts
26
+ - /cli/commands/approve-scripts
27
+ - /cli/commands/npm-approve-scripts
28
+ - /cli/npm-approve-scripts
29
+ - /cli/v11/approve-scripts
30
+ - /cli/v11/cli-commands/approve-scripts
31
+ - /cli/v11/cli-commands/npm-approve-scripts
32
+ - /cli/v11/commands/approve-scripts
33
+ - /cli/v11/npm-approve-scripts
34
+ - /commands/approve-scripts
35
+ - /commands/npm-approve-scripts
36
+---
37
+
38
+### Synopsis
39
+
40
+```bash
41
+npm approve-scripts <pkg> [<pkg> ...]
42
+npm approve-scripts --all
43
+npm approve-scripts --allow-scripts-pending
44
+```
45
+
46
+Note: This command is unaware of workspaces.
47
+
48
+### Description
49
+
50
+Manages the `allowScripts` field in your project's `package.json`, which records which of your dependencies are permitted to run install scripts (`preinstall`, `install`, `postinstall`, and `prepare` for non-registry sources). This command is the recommended way to maintain that field.
51
+
52
+In the current release, this field is advisory: install scripts still run by default, but installs print a list of packages whose scripts have not been reviewed. A future release will block unreviewed install scripts.
53
+
54
+There are three modes:
55
+
56
+```bash
57
+npm approve-scripts <pkg> [<pkg> ...]
58
+npm approve-scripts --all
59
+npm approve-scripts --allow-scripts-pending
60
+```
61
+
62
+`<pkg>` matches every installed version of that package. By default the command writes pinned entries (`pkg@1.2.3`), which keep their approval narrowed to the specific version you reviewed. Pass `--no-allow-scripts-pin` to write name-only entries that allow any future version.
63
+
64
+`--all` approves every package with unreviewed install scripts in one go.
65
+
66
+`--allow-scripts-pending` is read-only: it lists every package whose install scripts are not yet covered by `allowScripts`, without modifying `package.json`.
67
+
68
+`approve-scripts` honours the asymmetric pin rule: if you re-approve a package whose installed version has changed, the existing pin is rewritten to track the new installed version. Multi-version statements (`pkg@1 || 2`) are left alone, since they likely capture intent that the command cannot infer. Existing `false` entries always win; `approve-scripts` will not silently re-allow a package you previously denied.
69
+
70
+### Examples
71
+
72
+```bash
73
+# Approve all currently-installed install scripts after reviewing them
74
+npm approve-scripts --all
75
+
76
+# Approve specific packages, pinned to their installed version
77
+npm approve-scripts canvas sharp
78
+
79
+# Approve name-only (any version of this package is allowed)
80
+npm approve-scripts --no-allow-scripts-pin canvas
81
+
82
+# Preview which packages still need review
83
+npm approve-scripts --allow-scripts-pending
84
+```
85
+
86
+### Configuration
87
+
88
+#### `all`
89
+
90
+- Default: false
91
+- Type: Boolean
92
+
93
+When running `npm outdated` and `npm ls`, setting `--all` will show all outdated or installed packages, rather than only those directly depended upon by the current project.
94
+
95
+#### `allow-scripts-pending`
96
+
97
+- Default: false
98
+- Type: Boolean
99
+
100
+List packages with install scripts that are not yet covered by the `allowScripts` policy, without modifying `package.json`. Only meaningful for `npm approve-scripts`.
101
+
102
+#### `allow-scripts-pin`
103
+
104
+- Default: true
105
+- Type: Boolean
106
+
107
+Write pinned (`pkg@version`) entries when approving install scripts. Set to `false` to write name-only entries that allow any version. Has no effect on `npm deny-scripts`, which always writes name-only entries regardless of this setting.
108
+
109
+#### `json`
110
+
111
+- Default: false
112
+- Type: Boolean
113
+
114
+Whether or not to output JSON data, rather than the normal output.
115
+
116
+- In `npm pkg set` it enables parsing set values with JSON.parse() before saving them to your `package.json`.
117
+
118
+Not supported by all npm commands.
119
+
120
+### See Also
121
+
122
+- [npm deny-scripts](/cli/v11/commands/npm-deny-scripts)
123
+- [npm install](/cli/v11/commands/npm-install)
124
+- [npm rebuild](/cli/v11/commands/npm-rebuild)
125
+- [package.json](/cli/v11/configuring-npm/package-json)
content/cli/v11/commands/npm-ci.mdx
+27
@@ -201,6 +201,33 @@ Limits the ability for npm to fetch dependencies from urls. That is, dependencie
201
202
`all` allows any url to be installed. `none` prevents any url from being installed. `root` only allows urls defined in your project's package.json to be installed. Also allows url dependencies to be used for other commands like `npm view`
203
204
+#### `allow-scripts`
205
+
206
+- Default: ""
207
+- Type: String (can be set multiple times)
208
+
209
+Comma-separated list of packages whose install-time lifecycle scripts (`preinstall`, `install`, `postinstall`, and `prepare` for non-registry dependencies) are allowed to run.
210
+
211
+This setting is intended for one-off and global contexts: `npm exec`, `npx`, and `npm install -g`, where no project `package.json` is involved. For team-wide policy in a project, use the `allowScripts` field in `package.json` (which also supports explicit denials), or configure it in `.npmrc`. Passing `--allow-scripts` on the command line during a project-scoped `npm install`, `ci`, `update`, or `rebuild` is an error.
212
+
213
+Each name is matched against a dependency's resolved identity, not against the package's self-reported name. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
214
+
215
+#### `strict-allow-scripts`
216
+
217
+- Default: false
218
+- Type: Boolean
219
+
220
+If `true`, turn the install-script policy from a warning into a hard error: any dependency with install scripts not covered by `allowScripts` will fail the install instead of running with a notice.
221
+
222
+Dependencies explicitly denied with `false` in `allowScripts` are always silently skipped; this setting only affects unreviewed entries. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
223
+
224
+#### `dangerously-allow-all-scripts`
225
+
226
+- Default: false
227
+- Type: Boolean
228
+
229
+If `true`, bypass the `allowScripts` policy entirely and run every dependency install script regardless of whether it was approved or denied. Intended as a migration escape hatch only; its use is strongly discouraged. `--ignore-scripts` still takes precedence over this setting.
230
+
231
#### `audit`
232
233
- Default: true
content/cli/v11/commands/npm-deny-scripts.mdx
new
+112
@@ -0,0 +1,112 @@
1
+---
2
+title: npm-deny-scripts
3
+section: 1
4
+description: Deny install scripts for specific dependencies
5
+github_repo: npm/cli
6
+github_branch: latest
7
+github_path: docs/lib/content/commands/npm-deny-scripts.md
8
+redirect_from:
9
+ - /cli-commands/deny-scripts
10
+ - /cli-commands/npm-deny-scripts
11
+ - /cli-documentation/cli-commands/deny-scripts
12
+ - /cli-documentation/cli-commands/npm-deny-scripts
13
+ - /cli-documentation/commands/deny-scripts
14
+ - /cli-documentation/commands/npm-deny-scripts
15
+ - /cli-documentation/deny-scripts
16
+ - /cli-documentation/npm-deny-scripts
17
+ - /cli-documentation/v11/cli-commands/deny-scripts
18
+ - /cli-documentation/v11/cli-commands/npm-deny-scripts
19
+ - /cli-documentation/v11/commands/deny-scripts
20
+ - /cli-documentation/v11/commands/npm-deny-scripts
21
+ - /cli-documentation/v11/deny-scripts
22
+ - /cli-documentation/v11/npm-deny-scripts
23
+ - /cli/cli-commands/deny-scripts
24
+ - /cli/cli-commands/npm-deny-scripts
25
+ - /cli/commands/deny-scripts
26
+ - /cli/commands/npm-deny-scripts
27
+ - /cli/deny-scripts
28
+ - /cli/npm-deny-scripts
29
+ - /cli/v11/cli-commands/deny-scripts
30
+ - /cli/v11/cli-commands/npm-deny-scripts
31
+ - /cli/v11/commands/deny-scripts
32
+ - /cli/v11/deny-scripts
33
+ - /cli/v11/npm-deny-scripts
34
+ - /commands/deny-scripts
35
+ - /commands/npm-deny-scripts
36
+---
37
+
38
+### Synopsis
39
+
40
+```bash
41
+npm deny-scripts <pkg> [<pkg> ...]
42
+npm deny-scripts --all
43
+```
44
+
45
+Note: This command is unaware of workspaces.
46
+
47
+### Description
48
+
49
+The companion command to [`npm approve-scripts`](/cli/v11/commands/npm-approve-scripts). Writes `false` entries into the `allowScripts` field of your project's `package.json`, recording that a dependency must not run install scripts even if a future version would otherwise be eligible.
50
+
51
+In the current release, install scripts still run by default, so `deny-scripts` only affects how installs of denied packages are reported. A future release will block unreviewed install scripts and respect deny entries at install time.
52
+
53
+```bash
54
+npm deny-scripts <pkg> [<pkg> ...]
55
+npm deny-scripts --all
56
+```
57
+
58
+`<pkg>` matches every installed version of that package. Denies are always written name-only (`"pkg": false`), regardless of `--allow-scripts-pin`. Pinning a deny to a specific version would silently re-allow scripts for any other version of the same package, which defeats the purpose; the command picks the safer default for you.
59
+
60
+`--all` denies every package with unreviewed install scripts.
61
+
62
+If a `true` (pinned or name-only) entry exists for a package and you then deny it, the existing allow entries are removed so the name-only deny is unambiguous.
63
+
64
+### Examples
65
+
66
+```bash
67
+# Deny a specific package outright
68
+npm deny-scripts telemetry-pkg
69
+
70
+# Deny everything that has install scripts and isn't already approved
71
+npm deny-scripts --all
72
+```
73
+
74
+### Configuration
75
+
76
+#### `all`
77
+
78
+- Default: false
79
+- Type: Boolean
80
+
81
+When running `npm outdated` and `npm ls`, setting `--all` will show all outdated or installed packages, rather than only those directly depended upon by the current project.
82
+
83
+#### `allow-scripts-pending`
84
+
85
+- Default: false
86
+- Type: Boolean
87
+
88
+List packages with install scripts that are not yet covered by the `allowScripts` policy, without modifying `package.json`. Only meaningful for `npm approve-scripts`.
89
+
90
+#### `allow-scripts-pin`
91
+
92
+- Default: true
93
+- Type: Boolean
94
+
95
+Write pinned (`pkg@version`) entries when approving install scripts. Set to `false` to write name-only entries that allow any version. Has no effect on `npm deny-scripts`, which always writes name-only entries regardless of this setting.
96
+
97
+#### `json`
98
+
99
+- Default: false
100
+- Type: Boolean
101
+
102
+Whether or not to output JSON data, rather than the normal output.
103
+
104
+- In `npm pkg set` it enables parsing set values with JSON.parse() before saving them to your `package.json`.
105
+
106
+Not supported by all npm commands.
107
+
108
+### See Also
109
+
110
+- [npm approve-scripts](/cli/v11/commands/npm-approve-scripts)
111
+- [npm install](/cli/v11/commands/npm-install)
112
+- [package.json](/cli/v11/configuring-npm/package-json)
content/cli/v11/commands/npm-exec.mdx
+27
@@ -163,6 +163,33 @@ When false, specifying individual workspaces via the `workspace` config, or all
163
164
This value is not exported to the environment for child processes.
165
166
+#### `allow-scripts`
167
+
168
+- Default: ""
169
+- Type: String (can be set multiple times)
170
+
171
+Comma-separated list of packages whose install-time lifecycle scripts (`preinstall`, `install`, `postinstall`, and `prepare` for non-registry dependencies) are allowed to run.
172
+
173
+This setting is intended for one-off and global contexts: `npm exec`, `npx`, and `npm install -g`, where no project `package.json` is involved. For team-wide policy in a project, use the `allowScripts` field in `package.json` (which also supports explicit denials), or configure it in `.npmrc`. Passing `--allow-scripts` on the command line during a project-scoped `npm install`, `ci`, `update`, or `rebuild` is an error.
174
+
175
+Each name is matched against a dependency's resolved identity, not against the package's self-reported name. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
176
+
177
+#### `strict-allow-scripts`
178
+
179
+- Default: false
180
+- Type: Boolean
181
+
182
+If `true`, turn the install-script policy from a warning into a hard error: any dependency with install scripts not covered by `allowScripts` will fail the install instead of running with a notice.
183
+
184
+Dependencies explicitly denied with `false` in `allowScripts` are always silently skipped; this setting only affects unreviewed entries. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
185
+
186
+#### `dangerously-allow-all-scripts`
187
+
188
+- Default: false
189
+- Type: Boolean
190
+
191
+If `true`, bypass the `allowScripts` policy entirely and run every dependency install script regardless of whether it was approved or denied. Intended as a migration escape hatch only; its use is strongly discouraged. `--ignore-scripts` still takes precedence over this setting.
192
+
193
### Examples
194
195
Run the version of `tap` in the local dependencies, with the provided arguments:
content/cli/v11/commands/npm-install-ci-test.mdx
+27
@@ -161,6 +161,33 @@ Limits the ability for npm to fetch dependencies from urls. That is, dependencie
161
162
`all` allows any url to be installed. `none` prevents any url from being installed. `root` only allows urls defined in your project's package.json to be installed. Also allows url dependencies to be used for other commands like `npm view`
163
164
+#### `allow-scripts`
165
+
166
+- Default: ""
167
+- Type: String (can be set multiple times)
168
+
169
+Comma-separated list of packages whose install-time lifecycle scripts (`preinstall`, `install`, `postinstall`, and `prepare` for non-registry dependencies) are allowed to run.
170
+
171
+This setting is intended for one-off and global contexts: `npm exec`, `npx`, and `npm install -g`, where no project `package.json` is involved. For team-wide policy in a project, use the `allowScripts` field in `package.json` (which also supports explicit denials), or configure it in `.npmrc`. Passing `--allow-scripts` on the command line during a project-scoped `npm install`, `ci`, `update`, or `rebuild` is an error.
172
+
173
+Each name is matched against a dependency's resolved identity, not against the package's self-reported name. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
174
+
175
+#### `strict-allow-scripts`
176
+
177
+- Default: false
178
+- Type: Boolean
179
+
180
+If `true`, turn the install-script policy from a warning into a hard error: any dependency with install scripts not covered by `allowScripts` will fail the install instead of running with a notice.
181
+
182
+Dependencies explicitly denied with `false` in `allowScripts` are always silently skipped; this setting only affects unreviewed entries. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
183
+
184
+#### `dangerously-allow-all-scripts`
185
+
186
+- Default: false
187
+- Type: Boolean
188
+
189
+If `true`, bypass the `allowScripts` policy entirely and run every dependency install script regardless of whether it was approved or denied. Intended as a migration escape hatch only; its use is strongly discouraged. `--ignore-scripts` still takes precedence over this setting.
190
+
191
#### `audit`
192
193
- Default: true
content/cli/v11/commands/npm-install-test.mdx
+27
@@ -215,6 +215,33 @@ Limits the ability for npm to fetch dependencies from urls. That is, dependencie
215
216
`all` allows any url to be installed. `none` prevents any url from being installed. `root` only allows urls defined in your project's package.json to be installed. Also allows url dependencies to be used for other commands like `npm view`
217
218
+#### `allow-scripts`
219
+
220
+- Default: ""
221
+- Type: String (can be set multiple times)
222
+
223
+Comma-separated list of packages whose install-time lifecycle scripts (`preinstall`, `install`, `postinstall`, and `prepare` for non-registry dependencies) are allowed to run.
224
+
225
+This setting is intended for one-off and global contexts: `npm exec`, `npx`, and `npm install -g`, where no project `package.json` is involved. For team-wide policy in a project, use the `allowScripts` field in `package.json` (which also supports explicit denials), or configure it in `.npmrc`. Passing `--allow-scripts` on the command line during a project-scoped `npm install`, `ci`, `update`, or `rebuild` is an error.
226
+
227
+Each name is matched against a dependency's resolved identity, not against the package's self-reported name. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
228
+
229
+#### `strict-allow-scripts`
230
+
231
+- Default: false
232
+- Type: Boolean
233
+
234
+If `true`, turn the install-script policy from a warning into a hard error: any dependency with install scripts not covered by `allowScripts` will fail the install instead of running with a notice.
235
+
236
+Dependencies explicitly denied with `false` in `allowScripts` are always silently skipped; this setting only affects unreviewed entries. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
237
+
238
+#### `dangerously-allow-all-scripts`
239
+
240
+- Default: false
241
+- Type: Boolean
242
+
243
+If `true`, bypass the `allowScripts` policy entirely and run every dependency install script regardless of whether it was approved or denied. Intended as a migration escape hatch only; its use is strongly discouraged. `--ignore-scripts` still takes precedence over this setting.
244
+
245
#### `audit`
246
247
- Default: true
content/cli/v11/commands/npm-install.mdx
+27
@@ -519,6 +519,33 @@ Limits the ability for npm to fetch dependencies from urls. That is, dependencie
519
520
`all` allows any url to be installed. `none` prevents any url from being installed. `root` only allows urls defined in your project's package.json to be installed. Also allows url dependencies to be used for other commands like `npm view`
521
522
+#### `allow-scripts`
523
+
524
+- Default: ""
525
+- Type: String (can be set multiple times)
526
+
527
+Comma-separated list of packages whose install-time lifecycle scripts (`preinstall`, `install`, `postinstall`, and `prepare` for non-registry dependencies) are allowed to run.
528
+
529
+This setting is intended for one-off and global contexts: `npm exec`, `npx`, and `npm install -g`, where no project `package.json` is involved. For team-wide policy in a project, use the `allowScripts` field in `package.json` (which also supports explicit denials), or configure it in `.npmrc`. Passing `--allow-scripts` on the command line during a project-scoped `npm install`, `ci`, `update`, or `rebuild` is an error.
530
+
531
+Each name is matched against a dependency's resolved identity, not against the package's self-reported name. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
532
+
533
+#### `strict-allow-scripts`
534
+
535
+- Default: false
536
+- Type: Boolean
537
+
538
+If `true`, turn the install-script policy from a warning into a hard error: any dependency with install scripts not covered by `allowScripts` will fail the install instead of running with a notice.
539
+
540
+Dependencies explicitly denied with `false` in `allowScripts` are always silently skipped; this setting only affects unreviewed entries. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
541
+
542
+#### `dangerously-allow-all-scripts`
543
+
544
+- Default: false
545
+- Type: Boolean
546
+
547
+If `true`, bypass the `allowScripts` policy entirely and run every dependency install script regardless of whether it was approved or denied. Intended as a migration escape hatch only; its use is strongly discouraged. `--ignore-scripts` still takes precedence over this setting.
548
+
549
#### `audit`
550
551
- Default: true
content/cli/v11/commands/npm-ls.mdx
+1
-1
@@ -52,7 +52,7 @@ Note: to get a "bottoms up" view of why a given package is included in the tree
52
Positional arguments are `name@version-range` identifiers, which will limit the results to only the paths to the packages named. Note that nested packages will _also_ show the paths to the specified packages. For example, running `npm ls promzard` in npm's source tree will show:
53
54
```bash
55
-npm@11.15.0 /path/to/npm
55
+npm@11.16.0 /path/to/npm
56
└─┬ init-package-json@0.0.4
57
└── promzard@0.1.5
58
```
content/cli/v11/commands/npm-publish.mdx
+3
-1
@@ -131,7 +131,7 @@ If used in the `npm publish` command, this is the tag that will be added to the
131
#### `access`
132
133
- Default: 'public' for new packages, existing packages it will not change the current level
134
-- Type: null, "restricted", or "public"
134
+- Type: null, "restricted", "public", or "private"
135
136
If you do not want your scoped package to be publicly viewable (and installable) set `--access=restricted`.
137
@@ -139,6 +139,8 @@ Unscoped packages cannot be set to `restricted`.
139
140
Note: This defaults to not changing the current access level for existing packages. Specifying a value of `restricted` or `public` during publish will change the access for an existing package the same way that `npm access set status` would.
141
142
+The value `private` is an alias for `restricted`.
143
+
144
#### `dry-run`
145
146
- Default: false
content/cli/v11/commands/npm-rebuild.mdx
+27
@@ -109,6 +109,33 @@ If true, npm does not run scripts specified in package.json files.
109
110
Note that commands explicitly intended to run a particular script, such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run` will still run their intended script if `ignore-scripts` is set, but they will _not_ run any pre- or post-scripts.
111
112
+#### `allow-scripts`
113
+
114
+- Default: ""
115
+- Type: String (can be set multiple times)
116
+
117
+Comma-separated list of packages whose install-time lifecycle scripts (`preinstall`, `install`, `postinstall`, and `prepare` for non-registry dependencies) are allowed to run.
118
+
119
+This setting is intended for one-off and global contexts: `npm exec`, `npx`, and `npm install -g`, where no project `package.json` is involved. For team-wide policy in a project, use the `allowScripts` field in `package.json` (which also supports explicit denials), or configure it in `.npmrc`. Passing `--allow-scripts` on the command line during a project-scoped `npm install`, `ci`, `update`, or `rebuild` is an error.
120
+
121
+Each name is matched against a dependency's resolved identity, not against the package's self-reported name. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
122
+
123
+#### `strict-allow-scripts`
124
+
125
+- Default: false
126
+- Type: Boolean
127
+
128
+If `true`, turn the install-script policy from a warning into a hard error: any dependency with install scripts not covered by `allowScripts` will fail the install instead of running with a notice.
129
+
130
+Dependencies explicitly denied with `false` in `allowScripts` are always silently skipped; this setting only affects unreviewed entries. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
131
+
132
+#### `dangerously-allow-all-scripts`
133
+
134
+- Default: false
135
+- Type: Boolean
136
+
137
+If `true`, bypass the `allowScripts` policy entirely and run every dependency install script regardless of whether it was approved or denied. Intended as a migration escape hatch only; its use is strongly discouraged. `--ignore-scripts` still takes precedence over this setting.
138
+
139
#### `workspace`
140
141
- Default:
content/cli/v11/commands/npm-stage.mdx
+7
-5
@@ -136,11 +136,13 @@ npm stage publish <package-spec>
136
| Flag | Default | Type | Description |
137
| --- | --- | --- | --- |
138
| `--tag` | "latest" | String | If you ask npm to install a package and don't tell it a specific version, then it will install the specified tag. It is the tag added to the package@version specified in the `npm dist-tag add` command, if no explicit tag is given. When used by the `npm diff` command, this is the tag used to fetch the tarball that will be compared with the local files by default. If used in the `npm publish` command, this is the tag that will be added to the package submitted to the registry. |
139
-| `--access` |
140
-
141
- 'public' for new packages, existing packages it will not change the current level
142
-
143
-| null, "restricted", or "public" | If you do not want your scoped package to be publicly viewable (and installable) set `--access=restricted`. Unscoped packages cannot be set to `restricted`. Note: This defaults to not changing the current access level for existing packages. Specifying a value of `restricted` or `public` during publish will change the access for an existing package the same way that `npm access set status` would. | | `--dry-run` | false | Boolean | Indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, `install`, `update`, `dedupe`, `uninstall`, as well as `pack` and `publish`. Note: This is NOT honored by other network related commands, eg `dist-tags`, `owner`, etc. | | `--otp` | null | null or String | This is a one-time password from a two-factor authenticator. It's needed when publishing or changing package permissions with `npm access`. If not set, and a registry response fails with a challenge for a one-time password, npm will prompt on the command line for one. | | `--workspace`, `-w` | | String (can be set multiple times) | Enable running a command in the context of the configured workspaces of the current project while filtering by running only the workspaces defined by this configuration option. Valid values for the `workspace` config are either: _ Workspace names _ Path to a workspace directory \* Path to a parent workspace directory (will result in selecting all workspaces within that folder) When set for the `npm init` command, this may be set to the folder of a workspace which does not yet exist, to create the folder and set it up as a brand new workspace within the project. | | `--workspaces` | null | null or Boolean | Set to true to run the command in the context of **all** configured workspaces. Explicitly setting this to false will cause commands like `install` to ignore workspaces altogether. When not set explicitly: - Commands that operate on the `node_modules` tree (install, update, etc.) will link workspaces into the `node_modules` folder. - Commands that do other things (test, exec, publish, etc.) will operate on the root project, _unless_ one or more workspaces are specified in the `workspace` config. | | `--include-workspace-root` | false | Boolean | Include the workspace root when workspaces are enabled for a command. When false, specifying individual workspaces via the `workspace` config, or all workspaces via the `workspaces` flag, will cause npm to operate only on the specified workspaces, and not on the root project. | | `--provenance` | false | Boolean | When publishing from a supported cloud CI/CD system, the package will be publicly linked to where it was built and published from. |
139
+| `--access` | 'public' for new packages, existing packages it will not change the current level | null, "restricted", "public", or "private" | If you do not want your scoped package to be publicly viewable (and installable) set `--access=restricted`. Unscoped packages cannot be set to `restricted`. Note: This defaults to not changing the current access level for existing packages. Specifying a value of `restricted` or `public` during publish will change the access for an existing package the same way that `npm access set status` would. The value `private` is an alias for `restricted`. |
140
+| `--dry-run` | false | Boolean | Indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, `install`, `update`, `dedupe`, `uninstall`, as well as `pack` and `publish`. Note: This is NOT honored by other network related commands, eg `dist-tags`, `owner`, etc. |
141
+| `--otp` | null | null or String | This is a one-time password from a two-factor authenticator. It's needed when publishing or changing package permissions with `npm access`. If not set, and a registry response fails with a challenge for a one-time password, npm will prompt on the command line for one. |
142
+| `--workspace`, `-w` | | String (can be set multiple times) | Enable running a command in the context of the configured workspaces of the current project while filtering by running only the workspaces defined by this configuration option. Valid values for the `workspace` config are either: _ Workspace names _ Path to a workspace directory \* Path to a parent workspace directory (will result in selecting all workspaces within that folder) When set for the `npm init` command, this may be set to the folder of a workspace which does not yet exist, to create the folder and set it up as a brand new workspace within the project. |
143
+| `--workspaces` | null | null or Boolean | Set to true to run the command in the context of **all** configured workspaces. Explicitly setting this to false will cause commands like `install` to ignore workspaces altogether. When not set explicitly: - Commands that operate on the `node_modules` tree (install, update, etc.) will link workspaces into the `node_modules` folder. - Commands that do other things (test, exec, publish, etc.) will operate on the root project, _unless_ one or more workspaces are specified in the `workspace` config. |
144
+| `--include-workspace-root` | false | Boolean | Include the workspace root when workspaces are enabled for a command. When false, specifying individual workspaces via the `workspace` config, or all workspaces via the `workspaces` flag, will cause npm to operate only on the specified workspaces, and not on the root project. |
145
+| `--provenance` | false | Boolean | When publishing from a supported cloud CI/CD system, the package will be publicly linked to where it was built and published from. |
146
147
### `npm stage list`
148
content/cli/v11/commands/npm-update.mdx
+27
@@ -264,6 +264,33 @@ If true, npm does not run scripts specified in package.json files.
264
265
Note that commands explicitly intended to run a particular script, such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run` will still run their intended script if `ignore-scripts` is set, but they will _not_ run any pre- or post-scripts.
266
267
+#### `allow-scripts`
268
+
269
+- Default: ""
270
+- Type: String (can be set multiple times)
271
+
272
+Comma-separated list of packages whose install-time lifecycle scripts (`preinstall`, `install`, `postinstall`, and `prepare` for non-registry dependencies) are allowed to run.
273
+
274
+This setting is intended for one-off and global contexts: `npm exec`, `npx`, and `npm install -g`, where no project `package.json` is involved. For team-wide policy in a project, use the `allowScripts` field in `package.json` (which also supports explicit denials), or configure it in `.npmrc`. Passing `--allow-scripts` on the command line during a project-scoped `npm install`, `ci`, `update`, or `rebuild` is an error.
275
+
276
+Each name is matched against a dependency's resolved identity, not against the package's self-reported name. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
277
+
278
+#### `strict-allow-scripts`
279
+
280
+- Default: false
281
+- Type: Boolean
282
+
283
+If `true`, turn the install-script policy from a warning into a hard error: any dependency with install scripts not covered by `allowScripts` will fail the install instead of running with a notice.
284
+
285
+Dependencies explicitly denied with `false` in `allowScripts` are always silently skipped; this setting only affects unreviewed entries. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
286
+
287
+#### `dangerously-allow-all-scripts`
288
+
289
+- Default: false
290
+- Type: Boolean
291
+
292
+If `true`, bypass the `allowScripts` policy entirely and run every dependency install script regardless of whether it was approved or denied. Intended as a migration escape hatch only; its use is strongly discouraged. `--ignore-scripts` still takes precedence over this setting.
293
+
294
#### `audit`
295
296
- Default: true
content/cli/v11/commands/npm-version.mdx
+2
@@ -202,6 +202,8 @@ The exact order of execution is as follows:
202
5. Commit and tag.
203
6. Run the `postversion` script. Use it to clean up the file system or automatically push the commit and/or tag.
204
205
+For the `preversion`, `version` and `postversion` scripts, npm also sets the [environment variables](/cli/v11/using-npm/scripts#environment) `npm_old_version` and `npm_new_version`.
206
+
207
Take the following example:
208
209
```json
content/cli/v11/commands/npm.mdx
+1
-1
@@ -31,7 +31,7 @@ Note: This command is unaware of workspaces.
31
32
### Version
33
34
-11.15.0
34
+11.16.0
35
36
### Description
37
content/cli/v11/using-npm/config.mdx
+44
-1
@@ -135,7 +135,7 @@ Warning: This should generally not be set via a command-line option. It is safer
135
#### `access`
136
137
- Default: 'public' for new packages, existing packages it will not change the current level
138
-- Type: null, "restricted", or "public"
138
+- Type: null, "restricted", "public", or "private"
139
140
If you do not want your scoped package to be publicly viewable (and installable) set `--access=restricted`.
141
@@ -143,6 +143,8 @@ Unscoped packages cannot be set to `restricted`.
143
144
Note: This defaults to not changing the current access level for existing packages. Specifying a value of `restricted` or `public` during publish will change the access for an existing package the same way that `npm access set status` would.
145
146
+The value `private` is an alias for `restricted`.
147
+
148
#### `all`
149
150
- Default: false
@@ -193,6 +195,31 @@ Limits the ability for npm to fetch dependencies from urls. That is, dependencie
195
196
Prevents throwing an error when `npm version` is used to set the new version to the same value as the current version.
197
198
+#### `allow-scripts`
199
+
200
+- Default: ""
201
+- Type: String (can be set multiple times)
202
+
203
+Comma-separated list of packages whose install-time lifecycle scripts (`preinstall`, `install`, `postinstall`, and `prepare` for non-registry dependencies) are allowed to run.
204
+
205
+This setting is intended for one-off and global contexts: `npm exec`, `npx`, and `npm install -g`, where no project `package.json` is involved. For team-wide policy in a project, use the `allowScripts` field in `package.json` (which also supports explicit denials), or configure it in `.npmrc`. Passing `--allow-scripts` on the command line during a project-scoped `npm install`, `ci`, `update`, or `rebuild` is an error.
206
+
207
+Each name is matched against a dependency's resolved identity, not against the package's self-reported name. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
208
+
209
+#### `allow-scripts-pending`
210
+
211
+- Default: false
212
+- Type: Boolean
213
+
214
+List packages with install scripts that are not yet covered by the `allowScripts` policy, without modifying `package.json`. Only meaningful for `npm approve-scripts`.
215
+
216
+#### `allow-scripts-pin`
217
+
218
+- Default: true
219
+- Type: Boolean
220
+
221
+Write pinned (`pkg@version`) entries when approving install scripts. Set to `false` to write name-only entries that allow any version. Has no effect on `npm deny-scripts`, which always writes name-only entries regardless of this setting.
222
+
223
#### `audit`
224
225
- Default: true
@@ -327,6 +354,13 @@ Run git commit hooks when using the `npm version` command.
354
355
Override CPU architecture of native modules to install. Acceptable values are same as `cpu` field of package.json, which comes from `process.arch`.
356
357
+#### `dangerously-allow-all-scripts`
358
+
359
+- Default: false
360
+- Type: Boolean
361
+
362
+If `true`, bypass the `allowScripts` policy entirely and run every dependency install script regardless of whether it was approved or denied. Intended as a migration escape hatch only; its use is strongly discouraged. `--ignore-scripts` still takes precedence over this setting.
363
+
364
#### `depth`
365
366
- Default: `Infinity` if `--all` is set; otherwise, `0`
@@ -1275,6 +1309,15 @@ If set to true, then the `npm version` command will tag the version using `-s` t
1309
1310
Note that git requires you to have set up GPG keys in your git configs for this to work properly.
1311
1312
+#### `strict-allow-scripts`
1313
+
1314
+- Default: false
1315
+- Type: Boolean
1316
+
1317
+If `true`, turn the install-script policy from a warning into a hard error: any dependency with install scripts not covered by `allowScripts` will fail the install instead of running with a notice.
1318
+
1319
+Dependencies explicitly denied with `false` in `allowScripts` are always silently skipped; this setting only affects unreviewed entries. `--ignore-scripts` and `--dangerously-allow-all-scripts` both override this setting.
1320
+
1321
#### `strict-peer-deps`
1322
1323
- Default: false
content/cli/v11/using-npm/scripts.mdx
+7
@@ -283,6 +283,13 @@ For example, if you had `{"name":"foo", "version":"1.2.5"}` in your package.json
283
284
See [`package.json`](/cli/v11/configuring-npm/package-json) for more on package configs.
285
286
+#### versioning variables
287
+
288
+For versioning scripts (`preversion`, `version`, `postversion`), npm sets these environment variables:
289
+
290
+- `npm_old_version` - The version before being bumped
291
+- `npm_new_version` – The version after being bumped
292
+
293
#### current lifecycle event
294
295
Lastly, the `npm_lifecycle_event` environment variable is set to whichever stage of the cycle is being executed. So, you could have a single script used for different parts of the process which switches based on what's currently happening.
content/nav.yml
+7
-1
@@ -1598,7 +1598,7 @@
1598
- title: Changelog
1599
url: /cli/v10/using-npm/changelog
1600
description: Changelog notes for each version
1601
- - title: Version 11.15.0
1601
+ - title: Version 11.16.0
1602
shortName: v11
1603
url: /cli/v11
1604
default: true
@@ -1614,6 +1614,9 @@
1614
- title: npm access
1615
url: /cli/v11/commands/npm-access
1616
description: Set access level on published packages
1617
+ - title: npm approve-scripts
1618
+ url: /cli/v11/commands/npm-approve-scripts
1619
+ description: Approve install scripts for specific dependencies
1620
- title: npm audit
1621
url: /cli/v11/commands/npm-audit
1622
description: Run a security audit
@@ -1635,6 +1638,9 @@
1638
- title: npm dedupe
1639
url: /cli/v11/commands/npm-dedupe
1640
description: Reduce duplication in the package tree
1641
+ - title: npm deny-scripts
1642
+ url: /cli/v11/commands/npm-deny-scripts
1643
+ description: Deny install scripts for specific dependencies
1644
- title: npm deprecate
1645
url: /cli/v11/commands/npm-deprecate
1646
description: Deprecate a version of a package