CLI documentation update from CI

Author: npm-cli-bot

cli-cache.json

@@ -2,5 +2,5 @@
   "v8": "aa8fff11cdab94fff1a2160ee5241f5f4632e96b",
   "v9": "64763a341e7aa5b456e696f956759bf9b3440dc1",
   "v10": "6755ca2d5301b079f9e2581fc72ba2a612171364",
-  "v11": "54929cef8e26a4698234e5d2499a43b746569b12"
+  "v11": "4ebb831d93f13cc0b980754bf36abb2982b131f7"
 }

content/cli/v11/commands/npm-install.mdx

@@ -121,6 +121,8 @@ Even if you never publish your package, you can still get a lot of benefits of u
 
   In most cases, this will install the version of the modules tagged as `latest` on the npm registry.
 
+  **Note:** When installing by name without specifying a version or tag, npm prioritizes versions that match the current Node.js version based on the package's `engines` field. If the `latest` tag points to a version incompatible with your current Node.js version, npm will install the newest compatible version instead. To install a specific version regardless of `engines` compatibility, explicitly specify the version or tag: `npm install <name>@latest`.
+
   Example:
 
   ```bash
@@ -209,6 +211,15 @@ Even if you never publish your package, you can still get a lot of benefits of u
   npm install @myorg/privatepackage@"16 - 17"
   ```
 
+  **Prerelease versions:** By default, version ranges only match stable versions. To include prerelease versions, they must be explicitly specified in the range. Prerelease versions are tied to a specific version triple (major.minor.patch). For example, `^1.2.3-beta.1` will only match prereleases for `1.2.x`, not `1.3.x`. To match all prereleases for a major version, use a range like `^1.0.0-0`, which will include all `1.x.x` prereleases.
+
+  Example:
+
+  ```bash
+  npm install package@^1.2.3-beta.1  # Matches 1.2.3-beta.1, 1.2.3-beta.2, 1.2.4-beta.1, etc.
+  npm install package@^1.0.0-0       # Matches all 1.x.x prereleases and stable versions
+  ```
+
 - `npm install <git remote url>`:
 
   Installs the package from the hosted git provider, cloning it with `git`. For a full git remote url, only that URL will be attempted.
@@ -312,6 +323,8 @@ npm install sax@">=0.1.0 <0.2.0" bench supervisor
 
 The `--tag` argument will apply to all of the specified install targets. If a tag with the given name exists, the tagged version is preferred over newer versions.
 
+**Note:** The `--tag` option only affects packages specified on the command line. It does not override version ranges specified in `package.json`. For example, if `package.json` specifies `"foo": "^1.0.0"` and you run `npm install --tag beta`, npm will still install a version matching `^1.0.0` even if the `beta` tag points to a different version. To install a tagged version, specify the package explicitly: `npm install foo@beta`.
+
 The `--dry-run` argument will report in the usual way what the install would have done without actually installing anything.
 
 The `--package-lock-only` argument will only update the `package-lock.json`, instead of checking `node_modules` and downloading dependencies.

content/cli/v11/commands/npm-ls.mdx

@@ -52,7 +52,7 @@ Note: to get a "bottoms up" view of why a given package is included in the tree
 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:
 
 ```bash
-npm@11.6.4 /path/to/npm
+npm@11.7.0 /path/to/npm
 └─┬ init-package-json@0.0.4
   └── promzard@0.1.5
 ```

content/cli/v11/commands/npm-token.mdx

@@ -40,7 +40,7 @@ redirect_from:
 ```bash
 npm token list
 npm token revoke <id|token>
-npm token create --name=<name> [--token-description=<desc>] [--packages=<pkg1,pkg2>] [--packages-all] [--scopes=<scope1,scope2>] [--orgs=<org1,org2>] [--packages-and-scopes-permission=<read-only|read-write|no-access>] [--orgs-permission=<read-only|read-write|no-access>] [--expires=<days>] [--cidr=<ip-range>] [--bypass-2fa] [--password=<pass>]
+npm token create
 ```
 
 Note: This command is unaware of workspaces.
@@ -49,27 +49,21 @@ Note: This command is unaware of workspaces.
 
 This lets you list, create and revoke authentication tokens.
 
-- `npm token list`: Shows a table of all active authentication tokens. You can request this as JSON with `--json` or tab-separated values with `--parseable`.
+#### Listing tokens
 
-```
-Read only token npm_1f… with id 7f3134 created 2017-10-21
-
-Publish token npm_af…  with id c03241 created 2017-10-02
-with IP Whitelist: 192.168.0.1/24
+When listing tokens, an abbreviated token will be displayed. For security purposes the full token is not displayed.
 
-Publish token npm_… with id e0cf92 created 2017-10-02
+#### Generating tokens
 
-```
+When generating tokens, you will be prompted you for your password and, if you have two-factor authentication enabled, an otp.
 
-- `npm token create [--read-only] [--cidr=<cidr-ranges>]`: Create a new authentication token. It can be `--read-only`, or accept a list of [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) ranges with which to limit use of this token. This will prompt you for your password, and, if you have two-factor authentication enabled, an otp.
+Please refer to the [docs website](https://docs.npmjs.com/creating-and-viewing-access-tokens) for more information on generating tokens for CI/CD.
 
-  Currently, the cli cannot generate automation tokens. Please refer to the [docs website](https://docs.npmjs.com/creating-and-viewing-access-tokens) for more information on generating automation tokens.
+#### Revoking tokens
 
-```
-Created publish token a73c9572-f1b9-8983-983d-ba3ac3cc913d
-```
+When revoking a token, you can use the full token (e.g. what you get back from `npm token create`, or as can be found in an `.npmrc` file), or a truncated id. If the given truncated id is not distinct enough to differentiate between multiple existing tokens, you will need to use enough of the id to allow npm to distinguish between them. Full token ids can be found on the [npm website](https://www.npmjs.com), or in the `--parseable` or `--json` output of `npm token list`. This command will NOT accept the truncated token found in the normal `npm token list` output.
 
-- `npm token revoke <token|id>`: Immediately removes an authentication token from the registry. You will no longer be able to use it. This can accept both complete tokens (such as those you get back from `npm token create`, and those found in your `.npmrc`), and ids as seen in the parseable or json output of `npm token list`. This will NOT accept the truncated token found in the normal `npm token list` output.
+A revoked token will immediately be removed from the registry and you will no longer be able to use it.
 
 ### Configuration
 
@@ -99,7 +93,7 @@ When creating a Granular Access Token with `npm token create`, this sets the exp
 - Default:
 - Type: null or String (can be set multiple times)
 
-When creating a Granular Access Token with `npm token create`, this limits the token access to specific packages. Provide a comma-separated list of package names.
+When creating a Granular Access Token with `npm token create`, this limits the token access to specific packages.
 
 #### `packages-all`
 
@@ -113,14 +107,14 @@ When creating a Granular Access Token with `npm token create`, grants the token
 - Default: null
 - Type: null or String (can be set multiple times)
 
-When creating a Granular Access Token with `npm token create`, this limits the token access to specific scopes. Provide a comma-separated list of scope names (with or without @ prefix).
+When creating a Granular Access Token with `npm token create`, this limits the token access to specific scopes. Provide a scope name (with or without @ prefix).
 
 #### `orgs`
 
 - Default: null
 - Type: null or String (can be set multiple times)
 
-When creating a Granular Access Token with `npm token create`, this limits the token access to specific organizations. Provide a comma-separated list of organization names.
+When creating a Granular Access Token with `npm token create`, this limits the token access to specific organizations.
 
 #### `packages-and-scopes-permission`
 

content/cli/v11/commands/npm-version.mdx

@@ -167,8 +167,12 @@ Run this in a package directory to bump the version and write the new data back
 
 The `newversion` argument should be a valid semver string, a valid second argument to [semver.inc](https://github.com/npm/node-semver#functions) (one of `patch`, `minor`, `major`, `prepatch`, `preminor`, `premajor`, `prerelease`), or `from-git`. In the second case, the existing version will be incremented by 1 in the specified field. `from-git` will try to read the latest git tag, and use that as the new npm version.
 
+**Note:** If the current version is a prerelease version, `patch` will simply remove the prerelease suffix without incrementing the patch version number. For example, `1.2.0-5` becomes `1.2.0` with `npm version patch`, not `1.2.1`.
+
 If run in a git repo, it will also create a version commit and tag. This behavior is controlled by `git-tag-version` (see below), and can be disabled on the command line by running `npm --no-git-tag-version version`. It will fail if the working directory is not clean, unless the `-f` or `--force` flag is set.
 
+**Note:** Git integration requires a reasonably recent version of git (2.0.0 or later is recommended). If you encounter issues with git commands, ensure your git installation is up to date.
+
 If supplied with `-m` or [`--message` config](/cli/v11/using-npm/config#message) option, npm will use it as a commit message when creating a version commit. If the `message` config contains `%s` then that will be replaced with the resulting version number. For example:
 
 ```bash

content/cli/v11/commands/npm-view.mdx

@@ -97,6 +97,20 @@ If the field value you are querying for is a property of an object, you should r
 npm view express time'[4.8.0]'
 ```
 
+Note: When accessing object properties that contain special characters or numeric keys, you need to use quotes around the key name. For example, to get the publish time of a specific version:
+
+```bash
+npm view express "time[4.17.1]"
+```
+
+Without quotes, the shell may interpret the square brackets as glob patterns, causing the command to fail. You can also access the time field for a specific version by specifying the version in the package descriptor:
+
+```bash
+npm view express@4.17.1 time
+```
+
+This will return all version-time pairs, but the context will be for that specific version.
+
 Multiple fields may be specified, and will be printed one after another. For example, to get all the contributor names and email addresses, you can do this:
 
 ```bash
@@ -121,6 +135,56 @@ To show the `connect` package version history, you can do this:
 npm view connect versions
 ```
 
+### Field Access Patterns
+
+The `npm view` command supports different ways to access nested fields and array elements in package metadata. Understanding these patterns makes it easier to extract specific information.
+
+#### Nested Object Fields
+
+Use dot notation to access nested object fields:
+
+```bash
+# Access nested properties
+npm view npm repository.url
+npm view express bugs.url
+```
+
+#### Array Element Access
+
+For arrays, use numeric indices in square brackets to access specific elements:
+
+```bash
+# Get the first contributor's email
+npm view express contributors[0].email
+
+# Get the second maintainer's name
+npm view express maintainers[1].name
+```
+
+#### Object Property Access
+
+For object properties (like accessing specific versions in the `time` field), use bracket notation with the property name in quotes:
+
+```bash
+# Get publish time for a specific version
+npm view express "time[4.17.1]"
+
+# Get dist-tags
+npm view express "dist-tags.latest"
+```
+
+#### Extracting Fields from Arrays
+
+Request a non-numeric field on an array to get all values from objects in the list:
+
+```bash
+# Get all contributor emails
+npm view express contributors.email
+
+# Get all contributor names
+npm view express contributors.name
+```
+
 ### Configuration
 
 #### `json`

content/cli/v11/commands/npm.mdx

@@ -31,7 +31,7 @@ Note: This command is unaware of workspaces.
 
 ### Version
 
-11.6.4
+11.7.0
 
 ### Description
 

content/cli/v11/commands/npx.mdx

@@ -34,6 +34,8 @@ npx --package=foo -c '<cmd> [args...]'
 
 This command allows you to run an arbitrary command from an npm package (either one installed locally, or fetched remotely), in a similar context as running it via `npm run`.
 
+Run this command to execute a package's binary. Any options and arguments after the package name are passed directly to the executed command, not to npx itself. For example, `npx create-react-app my-app --template typescript` will pass `my-app` and `--template typescript` to the `create-react-app` command. To see what options a specific package accepts, consult that package's documentation (e.g., at npmjs.com or in its repository).
+
 Whatever packages are specified by the `--package` option will be provided in the `PATH` of the executed command, along with any locally installed package executables. The `--package` option may be specified multiple times, to execute the supplied command in an environment where all specified packages are available.
 
 If any requested packages are not present in the local project dependencies, then they are installed to a folder in the npm cache, which is added to the `PATH` environment variable in the executed process. A prompt is printed (which can be suppressed by providing either `--yes` or `--no`).

content/cli/v11/configuring-npm/package-json.mdx

@@ -325,6 +325,12 @@ For most modules, it makes the most sense to have a main script and often not mu
 
 If `main` is not set, it defaults to `index.js` in the package's root folder.
 
+### type
+
+The `type` field defines how Node.js should interpret `.js` files in your package. This field is not used by npm.
+
+See the [Node.js documentation on the type field](https://nodejs.org/api/packages.html#type) for more information.
+
 ### browser
 
 If your module is meant to be used client-side the browser field should be used instead of the main field. This is helpful to hint users that it might rely on primitives that aren't available in Node.js modules. (e.g. `window`)
@@ -470,6 +476,19 @@ For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use the same
 }
 ```
 
+**Note on normalization:** When you publish a package, npm normalizes the `repository` field to the full object format with a `url` property. If you use a shorthand format (like `"npm/example"`), you'll see a warning during `npm publish` indicating that the field was auto-corrected. While the shorthand format currently works, it's recommended to use the full object format in your `package.json` to avoid warnings and ensure future compatibility:
+
+```json
+{
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/npm/example.git"
+  }
+}
+```
+
+You can run `npm pkg fix` to automatically convert shorthand formats to the normalized object format.
+
 If the `package.json` for your package is not in the root directory (for example if it is part of a monorepo), you can specify the directory in which it lives:
 
 ```json
@@ -488,6 +507,20 @@ The "scripts" property is a dictionary containing script commands that are run a
 
 See [`scripts`](/cli/v11/using-npm/scripts) to find out more about writing package scripts.
 
+### gypfile
+
+If you have a binding.gyp file in the root of your package and you have not defined your own `install` or `preinstall` scripts, npm will default to building your module using node-gyp.
+
+To prevent npm from automatically building your module with node-gyp, set `gypfile` to `false`:
+
+```json
+{
+  "gypfile": false
+}
+```
+
+This is useful for packages that include native addons but want to handle the build process differently, or packages that have a binding.gyp file but should not be built as a native addon.
+
 ### config
 
 A "config" object can be used to set configuration parameters used in package scripts that persist across upgrades. For instance, if a package had the following:
@@ -853,6 +886,52 @@ You may not set an override for a package that you directly depend on unless bot
 }
 ```
 
+#### Replacing a dependency with a fork
+
+You can replace a package with a different package or fork using several methods:
+
+**Using the `npm:` prefix to replace with a different package name:**
+
+```json
+{
+  "overrides": {
+    "package-name": "npm:@scope/forked-package@1.0.0"
+  }
+}
+```
+
+**Using a GitHub repository (supports branches, tags, or commit hashes):**
+
+```json
+{
+  "overrides": {
+    "package-name": "github:username/repo#branch-name"
+  }
+}
+```
+
+**Using a local file path:**
+
+```json
+{
+  "overrides": {
+    "package-name": "file:../local-fork"
+  }
+}
+```
+
+These replacement methods work for both top-level overrides and nested overrides. For example, to replace a transitive dependency with a fork:
+
+```json
+{
+  "overrides": {
+    "parent-package": {
+      "vulnerable-dep": "github:username/patched-fork#v2.0.1"
+    }
+  }
+}
+```
+
 ### engines
 
 You can specify the version of node that your stuff works on:

content/cli/v11/configuring-npm/package-lock-json.mdx

@@ -136,14 +136,16 @@ npm v7 ignores this section entirely if a `packages` section is present, but doe
 
 Dependency objects have the following fields:
 
-- version: a specifier that varies depending on the nature of the package, and is usable in fetching a new copy of it.
+- version: a specifier that varies depending on the nature of the package, and is usable in fetching a new copy of it. Note that for peer dependencies that are not installed, or optional dependencies that are not installed, this field may be omitted.
   - bundled dependencies: Regardless of source, this is a version number that is purely for informational purposes.
   - registry sources: This is a version number. (eg, `1.2.3`)
   - git sources: This is a git specifier with resolved committish. (eg, `git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e`)
   - http tarball sources: This is the URL of the tarball. (eg, `https://example.com/example-1.3.0.tgz`)
   - local tarball sources: This is the file URL of the tarball. (eg `file:///opt/storage/example-1.3.0.tgz`)
   - local link sources: This is the file URL of the link. (eg `file:libs/our-module`)
 
+  **Note:** The `version` field may be omitted for certain types of dependencies, such as optional peer dependencies that are not installed. In these cases, only metadata fields like `dev`, `optional`, and `peer` will be present.
+
 - integrity: A `sha512` or `sha1` [Standard Subresource Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) string for the artifact that was unpacked in this location. For git dependencies, this is the commit sha.
 
 - resolved: For registry sources this is path of the tarball relative to the registry URL. If the tarball URL isn't on the same server as the registry URL then this is a complete URL. `registry.npmjs.org` is a magic value meaning "the currently configured registry".