CLI documentation update from CI
npm CLI robot committed
Oct 6, 2023 at 19:57 UTC
ce02b88da082172ceac78f3430f4f5df9d824236
11 files changed
+497
-4
content/cli/v9/commands/npm-audit.md
+17
@@ -47,6 +47,13 @@ vulnerability is found. It may be useful in CI environments to include the
47
will cause the command to fail. This option does not filter the report
48
output, it simply changes the command's failure threshold.
49
50
+### Package lock
51
+
52
+By default npm requires a package-lock or shrinkwrap in order to run the
53
+audit. You can bypass the package lock with `--no-package-lock` but be
54
+aware the results may be different with every run, since npm will
55
+re-build the dependency tree each time.
56
+
57
### Audit Signatures
58
59
To ensure the integrity of packages you download from the public npm registry, or any registry that supports signatures, you can verify the registry signatures of downloaded packages using the npm CLI.
@@ -336,6 +343,16 @@ For `list` this means the output will be based on the tree described by the
343
344
345
346
+#### `package-lock`
347
+
348
+* Default: true
349
+* Type: Boolean
350
+
351
+If set to false, then ignore `package-lock.json` files when installing. This
352
+will also prevent _writing_ `package-lock.json` if `save` is true.
353
+
354
+
355
+
356
#### `omit`
357
358
* Default: 'dev' if the `NODE_ENV` environment variable is set to
content/cli/v9/commands/npm-install-test.md
+20
@@ -271,6 +271,26 @@ Note: This is NOT honored by other network related commands, eg `dist-tags`,
271
272
273
274
+#### `cpu`
275
+
276
+* Default: null
277
+* Type: null or String
278
+
279
+Override CPU architecture of native modules to install. Acceptable values
280
+are same as `cpu` field of package.json, which comes from `process.arch`.
281
+
282
+
283
+
284
+#### `os`
285
+
286
+* Default: null
287
+* Type: null or String
288
+
289
+Override OS of native modules to install. Acceptable values are same as `os`
290
+field of package.json, which comes from `process.platform`.
291
+
292
+
293
+
294
#### `workspace`
295
296
* Default:
content/cli/v9/commands/npm-install.md
+20
@@ -661,6 +661,26 @@ Note: This is NOT honored by other network related commands, eg `dist-tags`,
661
662
663
664
+#### `cpu`
665
+
666
+* Default: null
667
+* Type: null or String
668
+
669
+Override CPU architecture of native modules to install. Acceptable values
670
+are same as `cpu` field of package.json, which comes from `process.arch`.
671
+
672
+
673
+
674
+#### `os`
675
+
676
+* Default: null
677
+* Type: null or String
678
+
679
+Override OS of native modules to install. Acceptable values are same as `os`
680
+field of package.json, which comes from `process.platform`.
681
+
682
+
683
+
684
#### `workspace`
685
686
* Default:
content/cli/v9/commands/npm-ls.md
+1
-1
@@ -42,7 +42,7 @@ packages will *also* show the paths to the specified packages. For
42
example, running `npm ls promzard` in npm's source tree will show:
43
44
```bash
45
-npm@9.8.1 /path/to/npm
45
+npm@9.9.0 /path/to/npm
46
└─┬ init-package-json@0.0.4
47
└── promzard@0.1.5
48
```
content/cli/v9/commands/npm-query.md
+29
@@ -150,6 +150,19 @@ npm query ":type(git)" | jq 'map(.name)' | xargs -I {} npm why {}
150
},
151
...
152
```
153
+### Package lock only mode
154
+
155
+If package-lock-only is enabled, only the information in the package
156
+lock (or shrinkwrap) is loaded. This means that information from the
157
+package.json files of your dependencies will not be included in the
158
+result set (e.g. description, homepage, engines).
159
+
160
+### Package lock only mode
161
+
162
+If package-lock-only is enabled, only the information in the package
163
+lock (or shrinkwrap) is loaded. This means that information from the
164
+package.json files of your dependencies will not be included in the
165
+result set (e.g. description, homepage, engines).
166
167
### Configuration
168
@@ -221,6 +234,22 @@ all workspaces via the `workspaces` flag, will cause npm to operate only on
234
the specified workspaces, and not on the root project.
235
236
This value is not exported to the environment for child processes.
237
+
238
+#### `package-lock-only`
239
+
240
+* Default: false
241
+* Type: Boolean
242
+
243
+If set to true, the current operation will only use the `package-lock.json`,
244
+ignoring `node_modules`.
245
+
246
+For `update` this means only the `package-lock.json` will be updated,
247
+instead of checking `node_modules` and downloading dependencies.
248
+
249
+For `list` this means the output will be based on the tree described by the
250
+`package-lock.json`, rather than the contents of `node_modules`.
251
+
252
+
253
## See Also
254
255
* [dependency selectors](/cli/v9/using-npm/dependency-selectors)
content/cli/v9/commands/npm-sbom.md
new
+334
@@ -0,0 +1,334 @@
1
+---
2
+title: npm-sbom
3
+section: 1
4
+description: Generate a Software Bill of Materials (SBOM)
5
+github_repo: npm/cli
6
+github_branch: release/v9
7
+github_path: docs/lib/content/commands/npm-sbom.md
8
+redirect_from:
9
+ - /cli-documentation/v9/cli-commands/npm-sbom
10
+ - /cli-documentation/v9/cli-commands/sbom
11
+ - /cli-documentation/v9/commands/npm-sbom
12
+ - /cli-documentation/v9/commands/sbom
13
+ - /cli-documentation/v9/npm-sbom
14
+ - /cli-documentation/v9/sbom
15
+ - /cli/v9/cli-commands/npm-sbom
16
+ - /cli/v9/cli-commands/sbom
17
+ - /cli/v9/commands/sbom
18
+ - /cli/v9/npm-sbom
19
+ - /cli/v9/sbom
20
+---
21
+
22
+### Synopsis
23
+
24
+```bash
25
+npm sbom
26
+```
27
+
28
+### Description
29
+
30
+The `npm sbom` command generates a Software Bill of Materials (SBOM) listing the
31
+dependencies for the current project. SBOMs can be generated in either
32
+[SPDX](https://spdx.dev/) or [CycloneDX](https://cyclonedx.org/) format.
33
+
34
+### Example CycloneDX SBOM
35
+
36
+```json
37
+{
38
+ "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
39
+ "bomFormat": "CycloneDX",
40
+ "specVersion": "1.5",
41
+ "serialNumber": "urn:uuid:09f55116-97e1-49cf-b3b8-44d0207e7730",
42
+ "version": 1,
43
+ "metadata": {
44
+ "timestamp": "2023-09-01T00:00:00.001Z",
45
+ "lifecycles": [
46
+ {
47
+ "phase": "build"
48
+ }
49
+ ],
50
+ "tools": [
51
+ {
52
+ "vendor": "npm",
53
+ "name": "cli",
54
+ "version": "10.1.0"
55
+ }
56
+ ],
57
+ "component": {
58
+ "bom-ref": "simple@1.0.0",
59
+ "type": "library",
60
+ "name": "simple",
61
+ "version": "1.0.0",
62
+ "scope": "required",
63
+ "author": "John Doe",
64
+ "description": "simple react app",
65
+ "purl": "pkg:npm/simple@1.0.0",
66
+ "properties": [
67
+ {
68
+ "name": "cdx:npm:package:path",
69
+ "value": ""
70
+ }
71
+ ],
72
+ "externalReferences": [],
73
+ "licenses": [
74
+ {
75
+ "license": {
76
+ "id": "MIT"
77
+ }
78
+ }
79
+ ]
80
+ }
81
+ },
82
+ "components": [
83
+ {
84
+ "bom-ref": "lodash@4.17.21",
85
+ "type": "library",
86
+ "name": "lodash",
87
+ "version": "4.17.21",
88
+ "scope": "required",
89
+ "author": "John-David Dalton",
90
+ "description": "Lodash modular utilities.",
91
+ "purl": "pkg:npm/lodash@4.17.21",
92
+ "properties": [
93
+ {
94
+ "name": "cdx:npm:package:path",
95
+ "value": "node_modules/lodash"
96
+ }
97
+ ],
98
+ "externalReferences": [
99
+ {
100
+ "type": "distribution",
101
+ "url": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz"
102
+ },
103
+ {
104
+ "type": "vcs",
105
+ "url": "git+https://github.com/lodash/lodash.git"
106
+ },
107
+ {
108
+ "type": "website",
109
+ "url": "https://lodash.com/"
110
+ },
111
+ {
112
+ "type": "issue-tracker",
113
+ "url": "https://github.com/lodash/lodash/issues"
114
+ }
115
+ ],
116
+ "hashes": [
117
+ {
118
+ "alg": "SHA-512",
119
+ "content": "bf690311ee7b95e713ba568322e3533f2dd1cb880b189e99d4edef13592b81764daec43e2c54c61d5c558dc5cfb35ecb85b65519e74026ff17675b6f8f916f4a"
120
+ }
121
+ ],
122
+ "licenses": [
123
+ {
124
+ "license": {
125
+ "id": "MIT"
126
+ }
127
+ }
128
+ ]
129
+ }
130
+ ],
131
+ "dependencies": [
132
+ {
133
+ "ref": "simple@1.0.0",
134
+ "dependsOn": [
135
+ "lodash@4.17.21"
136
+ ]
137
+ },
138
+ {
139
+ "ref": "lodash@4.17.21",
140
+ "dependsOn": []
141
+ }
142
+ ]
143
+}
144
+```
145
+
146
+### Example SPDX SBOM
147
+
148
+```json
149
+{
150
+ "spdxVersion": "SPDX-2.3",
151
+ "dataLicense": "CC0-1.0",
152
+ "SPDXID": "SPDXRef-DOCUMENT",
153
+ "name": "simple@1.0.0",
154
+ "documentNamespace": "http://spdx.org/spdxdocs/simple-1.0.0-bf81090e-8bbc-459d-bec9-abeb794e096a",
155
+ "creationInfo": {
156
+ "created": "2023-09-01T00:00:00.001Z",
157
+ "creators": [
158
+ "Tool: npm/cli-10.1.0"
159
+ ]
160
+ },
161
+ "documentDescribes": [
162
+ "SPDXRef-Package-simple-1.0.0"
163
+ ],
164
+ "packages": [
165
+ {
166
+ "name": "simple",
167
+ "SPDXID": "SPDXRef-Package-simple-1.0.0",
168
+ "versionInfo": "1.0.0",
169
+ "packageFileName": "",
170
+ "description": "simple react app",
171
+ "primaryPackagePurpose": "LIBRARY",
172
+ "downloadLocation": "NOASSERTION",
173
+ "filesAnalyzed": false,
174
+ "homepage": "NOASSERTION",
175
+ "licenseDeclared": "MIT",
176
+ "externalRefs": [
177
+ {
178
+ "referenceCategory": "PACKAGE-MANAGER",
179
+ "referenceType": "purl",
180
+ "referenceLocator": "pkg:npm/simple@1.0.0"
181
+ }
182
+ ]
183
+ },
184
+ {
185
+ "name": "lodash",
186
+ "SPDXID": "SPDXRef-Package-lodash-4.17.21",
187
+ "versionInfo": "4.17.21",
188
+ "packageFileName": "node_modules/lodash",
189
+ "description": "Lodash modular utilities.",
190
+ "downloadLocation": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
191
+ "filesAnalyzed": false,
192
+ "homepage": "https://lodash.com/",
193
+ "licenseDeclared": "MIT",
194
+ "externalRefs": [
195
+ {
196
+ "referenceCategory": "PACKAGE-MANAGER",
197
+ "referenceType": "purl",
198
+ "referenceLocator": "pkg:npm/lodash@4.17.21"
199
+ }
200
+ ],
201
+ "checksums": [
202
+ {
203
+ "algorithm": "SHA512",
204
+ "checksumValue": "bf690311ee7b95e713ba568322e3533f2dd1cb880b189e99d4edef13592b81764daec43e2c54c61d5c558dc5cfb35ecb85b65519e74026ff17675b6f8f916f4a"
205
+ }
206
+ ]
207
+ }
208
+ ],
209
+ "relationships": [
210
+ {
211
+ "spdxElementId": "SPDXRef-DOCUMENT",
212
+ "relatedSpdxElement": "SPDXRef-Package-simple-1.0.0",
213
+ "relationshipType": "DESCRIBES"
214
+ },
215
+ {
216
+ "spdxElementId": "SPDXRef-Package-simple-1.0.0",
217
+ "relatedSpdxElement": "SPDXRef-Package-lodash-4.17.21",
218
+ "relationshipType": "DEPENDS_ON"
219
+ }
220
+ ]
221
+}
222
+```
223
+
224
+### Package lock only mode
225
+
226
+If package-lock-only is enabled, only the information in the package
227
+lock (or shrinkwrap) is loaded. This means that information from the
228
+package.json files of your dependencies will not be included in the
229
+result set (e.g. description, homepage, engines).
230
+
231
+### Configuration
232
+
233
+#### `omit`
234
+
235
+* Default: 'dev' if the `NODE_ENV` environment variable is set to
236
+ 'production', otherwise empty.
237
+* Type: "dev", "optional", or "peer" (can be set multiple times)
238
+
239
+Dependency types to omit from the installation tree on disk.
240
+
241
+Note that these dependencies _are_ still resolved and added to the
242
+`package-lock.json` or `npm-shrinkwrap.json` file. They are just not
243
+physically installed on disk.
244
+
245
+If a package type appears in both the `--include` and `--omit` lists, then
246
+it will be included.
247
+
248
+If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment
249
+variable will be set to `'production'` for all lifecycle scripts.
250
+
251
+
252
+
253
+#### `package-lock-only`
254
+
255
+* Default: false
256
+* Type: Boolean
257
+
258
+If set to true, the current operation will only use the `package-lock.json`,
259
+ignoring `node_modules`.
260
+
261
+For `update` this means only the `package-lock.json` will be updated,
262
+instead of checking `node_modules` and downloading dependencies.
263
+
264
+For `list` this means the output will be based on the tree described by the
265
+`package-lock.json`, rather than the contents of `node_modules`.
266
+
267
+
268
+
269
+#### `sbom-format`
270
+
271
+* Default: null
272
+* Type: "cyclonedx" or "spdx"
273
+
274
+SBOM format to use when generating SBOMs.
275
+
276
+
277
+
278
+#### `sbom-type`
279
+
280
+* Default: "library"
281
+* Type: "library", "application", or "framework"
282
+
283
+The type of package described by the generated SBOM. For SPDX, this is the
284
+value for the `primaryPackagePurpose` field. For CycloneDX, this is the
285
+value for the `type` field.
286
+
287
+
288
+
289
+#### `workspace`
290
+
291
+* Default:
292
+* Type: String (can be set multiple times)
293
+
294
+Enable running a command in the context of the configured workspaces of the
295
+current project while filtering by running only the workspaces defined by
296
+this configuration option.
297
+
298
+Valid values for the `workspace` config are either:
299
+
300
+* Workspace names
301
+* Path to a workspace directory
302
+* Path to a parent workspace directory (will result in selecting all
303
+ workspaces within that folder)
304
+
305
+When set for the `npm init` command, this may be set to the folder of a
306
+workspace which does not yet exist, to create the folder and set it up as a
307
+brand new workspace within the project.
308
+
309
+This value is not exported to the environment for child processes.
310
+
311
+#### `workspaces`
312
+
313
+* Default: null
314
+* Type: null or Boolean
315
+
316
+Set to true to run the command in the context of **all** configured
317
+workspaces.
318
+
319
+Explicitly setting this to false will cause commands like `install` to
320
+ignore workspaces altogether. When not set explicitly:
321
+
322
+- Commands that operate on the `node_modules` tree (install, update, etc.)
323
+will link workspaces into the `node_modules` folder. - Commands that do
324
+other things (test, exec, publish, etc.) will operate on the root project,
325
+_unless_ one or more workspaces are specified in the `workspace` config.
326
+
327
+This value is not exported to the environment for child processes.
328
+## See Also
329
+
330
+* [package spec](/cli/v9/using-npm/package-spec)
331
+* [dependency selectors](/cli/v9/using-npm/dependency-selectors)
332
+* [package.json](/cli/v9/configuring-npm/package-json)
333
+* [workspaces](/cli/v9/using-npm/workspaces)
334
+
content/cli/v9/commands/npm.md
+1
-1
@@ -23,7 +23,7 @@ Note: This command is unaware of workspaces.
23
24
### Version
25
26
-9.8.1
26
+9.9.0
27
28
### Description
29
content/cli/v9/using-npm/changelog.md
+30
@@ -11,6 +11,36 @@ redirect_from:
11
12
# Changelog
13
14
+## [9.9.0](https://github.com/npm/cli/compare/v9.8.1...v9.9.0) (2023-10-06)
15
+
16
+### Features
17
+
18
+* [`ecda95a`](https://github.com/npm/cli/commit/ecda95a1eb08c5579815a7c8b27fd885a20f25af) [#6841](https://github.com/npm/cli/pull/6841) add npm sbom command (#6841) (@bdehamer)
19
+* [`fdb8a86`](https://github.com/npm/cli/commit/fdb8a863813b88da178358d246dc6f4bb48f1d2d) [#6794](https://github.com/npm/cli/pull/6794) add package-lock-only mode to npm query (@wraithgar)
20
+* [`16c04b1`](https://github.com/npm/cli/commit/16c04b1340a6046c27a6369a2acb891b714652dd) [#6877](https://github.com/npm/cli/pull/6877) add no-package-lock mode to npm audit (@wraithgar)
21
+* [`66ef765`](https://github.com/npm/cli/commit/66ef76539c5ee2f015b130f53aa2f325f1bf3f84) [#6776](https://github.com/npm/cli/pull/6776) Add `--cpu` and `--os` option to override platform specific install (#6776) (@yukukotani)
22
+
23
+### Bug Fixes
24
+
25
+* [`c9406f7`](https://github.com/npm/cli/commit/c9406f79dce12953f639df6add0c4215831e99b8) [#6791](https://github.com/npm/cli/pull/6791) deprecate: ignore implicit workspace mode (#6758) (#6791) (@wraithgar)
26
+* [`0b1d7c3`](https://github.com/npm/cli/commit/0b1d7c3e54f6b2ef1333087632048df3cb69f22d) [#6779](https://github.com/npm/cli/pull/6779) allow searching packages with no description (#6779) (@wraithgar, @lukekarrys)
27
+
28
+### Documentation
29
+
30
+* [`9750720`](https://github.com/npm/cli/commit/975072058e0fcec25074d73514cd50ea180b54fe) [#6694](https://github.com/npm/cli/pull/6694) fix example path (#6694) (@fvilers)
31
+
32
+### Dependencies
33
+
34
+* [`588a245`](https://github.com/npm/cli/commit/588a245191c4bf37f43a919809c54c205547811b) [#6756](https://github.com/npm/cli/pull/6756) `npm-pick-manifest@8.0.2`
35
+* [`a76b1df`](https://github.com/npm/cli/commit/a76b1df3a78231cac910a68b2f188b17c9a6c623) [#6877](https://github.com/npm/cli/pull/6877) `sigstore@1.9.0`
36
+* [`95b5ab0`](https://github.com/npm/cli/commit/95b5ab06785bd047b08ac0a84b986115774ead0f) [#6877](https://github.com/npm/cli/pull/6877) `npm-install-checks@6.2.0`
37
+* [Workspace](https://github.com/npm/cli/releases/tag/arborist-v6.5.0): `@npmcli/arborist@6.5.0`
38
+* [Workspace](https://github.com/npm/cli/releases/tag/config-v6.4.0): `@npmcli/config@6.4.0`
39
+* [Workspace](https://github.com/npm/cli/releases/tag/libnpmdiff-v5.0.20): `libnpmdiff@5.0.20`
40
+* [Workspace](https://github.com/npm/cli/releases/tag/libnpmexec-v6.0.4): `libnpmexec@6.0.4`
41
+* [Workspace](https://github.com/npm/cli/releases/tag/libnpmfund-v4.2.1): `libnpmfund@4.2.1`
42
+* [Workspace](https://github.com/npm/cli/releases/tag/libnpmpack-v5.0.20): `libnpmpack@5.0.20`
43
+
44
## [9.8.1](https://github.com/npm/cli/compare/v9.8.0...v9.8.1) (2023-07-18)
45
46
### Bug Fixes
content/cli/v9/using-npm/config.md
+40
@@ -352,6 +352,16 @@ Run git commit hooks when using the `npm version` command.
352
353
354
355
+#### `cpu`
356
+
357
+* Default: null
358
+* Type: null or String
359
+
360
+Override CPU architecture of native modules to install. Acceptable values
361
+are same as `cpu` field of package.json, which comes from `process.arch`.
362
+
363
+
364
+
365
#### `depth`
366
367
* Default: `Infinity` if `--all` is set, otherwise `1`
@@ -1045,6 +1055,16 @@ time.
1055
1056
1057
1058
+#### `os`
1059
+
1060
+* Default: null
1061
+* Type: null or String
1062
+
1063
+Override OS of native modules to install. Acceptable values are same as `os`
1064
+field of package.json, which comes from `process.platform`.
1065
+
1066
+
1067
+
1068
#### `otp`
1069
1070
* Default: null
@@ -1345,6 +1365,26 @@ or `--save-optional` are true.
1365
1366
1367
1368
+#### `sbom-format`
1369
+
1370
+* Default: null
1371
+* Type: "cyclonedx" or "spdx"
1372
+
1373
+SBOM format to use when generating SBOMs.
1374
+
1375
+
1376
+
1377
+#### `sbom-type`
1378
+
1379
+* Default: "library"
1380
+* Type: "library", "application", or "framework"
1381
+
1382
+The type of package described by the generated SBOM. For SPDX, this is the
1383
+value for the `primaryPackagePurpose` field. For CycloneDX, this is the
1384
+value for the `type` field.
1385
+
1386
+
1387
+
1388
#### `scope`
1389
1390
* Default: the scope of the current project, if any, or ""
content/cli/v9/using-npm/workspaces.md
+1
-1
@@ -109,7 +109,7 @@ the npm installer that package should be added as a dependency of the provided
109
workspace:
110
111
```
112
-npm install abbrev -w a
112
+npm install abbrev -w packages/a
113
```
114
115
Note: other installing commands such as `uninstall`, `ci`, etc will also
src/theme/nav.yml
+4
-1
@@ -1051,7 +1051,7 @@
1051
- title: Changelog
1052
url: /cli/v8/using-npm/changelog
1053
description: Changelog notes for each version
1054
- - title: Version 9.8.1 (Legacy Release)
1054
+ - title: Version 9.9.0 (Legacy Release)
1055
shortName: v9
1056
url: /cli/v9
1057
default: false
@@ -1204,6 +1204,9 @@
1204
- title: npm run-script
1205
url: /cli/v9/commands/npm-run-script
1206
description: Run arbitrary package scripts
1207
+ - title: npm sbom
1208
+ url: /cli/v9/commands/npm-sbom
1209
+ description: Generate a Software Bill of Materials (SBOM)
1210
- title: npm search
1211
url: /cli/v9/commands/npm-search
1212
description: Search for packages