diff --git a/docs/content/commands/npm-cache.md b/docs/content/commands/npm-cache.md
index 091e26e8a7182..b5eddd46c05a7 100644
--- a/docs/content/commands/npm-cache.md
+++ b/docs/content/commands/npm-cache.md
@@ -11,11 +11,7 @@ description: Manipulates packages cache
 <!-- see lib/commands/cache.js -->
 
 ```bash
-npm cache add <tarball file>
-npm cache add <folder>
-npm cache add <tarball url>
-npm cache add <git url>
-npm cache add <name>@<version>
+npm cache add <package-spec>
 npm cache clean [<key>]
 npm cache ls [<name>@<version>]
 npm cache verify
@@ -101,6 +97,7 @@ cache`](/commands/npm-cache)
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm folders](/configuring-npm/folders)
 * [npm config](/commands/npm-config)
 * [npmrc](/configuring-npm/npmrc)
diff --git a/docs/content/commands/npm-ci.md b/docs/content/commands/npm-ci.md
index 3374bf1e25136..9b8238d05a3b9 100644
--- a/docs/content/commands/npm-ci.md
+++ b/docs/content/commands/npm-ci.md
@@ -133,7 +133,7 @@ will *not* run any pre- or post-scripts.
 * Type: null or String
 
 The shell to use for scripts run with the `npm exec`, `npm run` and `npm
-init <pkg>` commands.
+init <package-spec>` commands.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
diff --git a/docs/content/commands/npm-deprecate.md b/docs/content/commands/npm-deprecate.md
index 4345120d3744b..20f65140fc735 100644
--- a/docs/content/commands/npm-deprecate.md
+++ b/docs/content/commands/npm-deprecate.md
@@ -11,7 +11,7 @@ description: Deprecate a version of a package
 <!-- see lib/commands/deprecate.js -->
 
 ```bash
-npm deprecate <pkg>[@<version>] <message>
+npm deprecate <package-spec> <message>
 ```
 
 <!-- automatically generated, do not edit manually -->
@@ -45,8 +45,8 @@ In this case, a version `my-thing@1.0.0-beta.0` will also be deprecated.
 You must be the package owner to deprecate something.  See the `owner` and
 `adduser` help topics.
 
-To un-deprecate a package, specify an empty string (`""`) for the `message` 
-argument. Note that you must use double quotes with no space between them to 
+To un-deprecate a package, specify an empty string (`""`) for the `message`
+argument. Note that you must use double quotes with no space between them to
 format an empty string.
 
 ### Configuration
@@ -82,6 +82,7 @@ password, npm will prompt on the command line for one.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm publish](/commands/npm-publish)
 * [npm registry](/using-npm/registry)
 * [npm owner](/commands/npm-owner)
diff --git a/docs/content/commands/npm-dist-tag.md b/docs/content/commands/npm-dist-tag.md
index b9caf1fbe7fa9..123e67dbf3b23 100644
--- a/docs/content/commands/npm-dist-tag.md
+++ b/docs/content/commands/npm-dist-tag.md
@@ -11,9 +11,9 @@ description: Modify package distribution tags
 <!-- see lib/commands/dist-tag.js -->
 
 ```bash
-npm dist-tag add <pkg>@<version> [<tag>]
-npm dist-tag rm <pkg> <tag>
-npm dist-tag ls [<pkg>]
+npm dist-tag add <package-spec (with version)> [<tag>]
+npm dist-tag rm <package-spec> <tag>
+npm dist-tag ls [<package-spec>]
 
 alias: dist-tags
 ```
@@ -27,11 +27,11 @@ alias: dist-tags
 
 Add, remove, and enumerate distribution tags on a package:
 
-* add: Tags the specified version of the package with the specified tag, or
-  the `--tag` config if not specified. If you have two-factor
-  authentication on auth-and-writes then you’ll need to include a one-time
-  password on the command line with `--otp <one-time password>`, or at the
-  OTP prompt.
+* add: Tags the specified version of the package with the specified tag,
+  or the `--tag` config if not specified. If you have two-factor
+  authentication on auth-and-writes then you’ll need to include a
+  one-time password on the command line with
+  `--otp <one-time password>`, or at the OTP prompt.
 
 * rm: Clear a tag that is no longer in use from the package. If you have
   two-factor authentication on auth-and-writes then you’ll need to include
@@ -168,6 +168,7 @@ This value is not exported to the environment for child processes.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm publish](/commands/npm-publish)
 * [npm install](/commands/npm-install)
 * [npm dedupe](/commands/npm-dedupe)
diff --git a/docs/content/commands/npm-explain.md b/docs/content/commands/npm-explain.md
index 765221056585d..5ba2fe8206ba1 100644
--- a/docs/content/commands/npm-explain.md
+++ b/docs/content/commands/npm-explain.md
@@ -11,7 +11,7 @@ description: Explain installed packages
 <!-- see lib/commands/explain.js -->
 
 ```bash
-npm explain <folder | specifier>
+npm explain <package-spec>
 
 alias: why
 ```
@@ -26,9 +26,10 @@ alias: why
 This command will print the chain of dependencies causing a given package
 to be installed in the current project.
 
-Positional arguments can be either folders within `node_modules`, or
-`name@version-range` specifiers, which will select the dependency
-relationships to explain.
+If one or more package specs are provided, then only packages matching
+one of the specifiers will have their relationships explained.
+
+The package spec can also refer to a folder within `./node_modules`
 
 For example, running `npm explain glob` within npm's source tree will show:
 
@@ -110,6 +111,7 @@ This value is not exported to the environment for child processes.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm config](/commands/npm-config)
 * [npmrc](/configuring-npm/npmrc)
 * [npm folders](/configuring-npm/folders)
diff --git a/docs/content/commands/npm-fund.md b/docs/content/commands/npm-fund.md
index 5b96e91ab8ccb..8db0ce910de96 100644
--- a/docs/content/commands/npm-fund.md
+++ b/docs/content/commands/npm-fund.md
@@ -11,7 +11,7 @@ description: Retrieve funding information
 <!-- see lib/commands/fund.js -->
 
 ```bash
-npm fund [[<@scope>/]<pkg>]
+npm fund [<package-spec>]
 ```
 
 <!-- automatically generated, do not edit manually -->
@@ -23,22 +23,22 @@ npm fund [[<@scope>/]<pkg>]
 
 This command retrieves information on how to fund the dependencies of a
 given project. If no package name is provided, it will list all
-dependencies that are looking for funding in a tree structure, listing the
-type of funding and the url to visit. If a package name is provided then it
-tries to open its funding url using the `--browser` config param; if there
-are multiple funding sources for the package, the user will be instructed
-to pass the `--which` option to disambiguate.
+dependencies that are looking for funding in a tree structure, listing
+the type of funding and the url to visit. If a package name is provided
+then it tries to open its funding url using the `--browser` config
+param; if there are multiple funding sources for the package, the user
+will be instructed to pass the `--which` option to disambiguate.
 
 The list will avoid duplicated entries and will stack all packages that
-share the same url as a single entry. Thus, the list does not have the same
-shape of the output from `npm ls`.
+share the same url as a single entry. Thus, the list does not have the
+same shape of the output from `npm ls`.
 
 #### Example
 
 ### Workspaces support
 
-It's possible to filter the results to only include a single workspace and its
-dependencies using the `workspace` config option.
+It's possible to filter the results to only include a single workspace
+and its dependencies using the `workspace` config option.
 
 #### Example:
 
@@ -58,8 +58,8 @@ test-workspaces-fund@1.0.0
     `-- bar@2.0.0
 ```
 
-And here is an example of the expected result when filtering only by
-a specific workspace `a` in the same project:
+And here is an example of the expected result when filtering only by a
+specific workspace `a` in the same project:
 
 ```bash
 $ npm fund -w a
@@ -156,6 +156,7 @@ If there are multiple funding sources, which 1-indexed source URL to open.
 
 ## See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm install](/commands/npm-install)
 * [npm docs](/commands/npm-docs)
 * [npm ls](/commands/npm-ls)
diff --git a/docs/content/commands/npm-init.md b/docs/content/commands/npm-init.md
index 35343cceb4aa1..cd0be4643e0ea 100644
--- a/docs/content/commands/npm-init.md
+++ b/docs/content/commands/npm-init.md
@@ -11,9 +11,8 @@ description: Create a package.json file
 <!-- see lib/commands/init.js -->
 
 ```bash
-npm init [--force|-f|--yes|-y|--scope]
+npm init <package-spec> (same as `npx <package-spec>)
 npm init <@scope> (same as `npx <@scope>/create`)
-npm init [<@scope>/]<name> (same as `npx [<@scope>/]create-<name>`)
 
 aliases: create, innit
 ```
@@ -204,6 +203,39 @@ mistakes, unnecessary performance degradation, and malicious input.
 If you don't have a clear idea of what you want to do, it is strongly
 recommended that you do not use this option!
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
+#### `scope`
+
+* Default: the scope of the current project, if any, or ""
+* Type: String
+
+Associate an operation with a scope for a scoped registry.
+
+Useful when logging in to or out of a private registry:
+
+```
+# log in, linking the scope to the custom registry
+npm login --scope=@mycorp --registry=https://registry.mycorp.com
+
+# log out, removing the link and the auth token
+npm logout --scope=@mycorp
+```
+
+This will cause `@mycorp` to be mapped to the registry for future
+installation of packages specified according to the pattern
+`@mycorp/package`.
+
+This will also cause `npm init` to create a scoped package.
+
+```
+# accept all defaults, and create a package named "@foo/whatever",
+# instead of just named "whatever"
+npm init --scope=@foo --yes
+```
+
+
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
@@ -284,6 +316,7 @@ This value is not exported to the environment for child processes.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [init-package-json module](http://npm.im/init-package-json)
 * [package.json](/configuring-npm/package-json)
 * [npm version](/commands/npm-version)
diff --git a/docs/content/commands/npm-install-ci-test.md b/docs/content/commands/npm-install-ci-test.md
index 0d9470acf58b3..74ed4667e81bf 100644
--- a/docs/content/commands/npm-install-ci-test.md
+++ b/docs/content/commands/npm-install-ci-test.md
@@ -79,7 +79,7 @@ will *not* run any pre- or post-scripts.
 * Type: null or String
 
 The shell to use for scripts run with the `npm exec`, `npm run` and `npm
-init <pkg>` commands.
+init <package-spec>` commands.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
diff --git a/docs/content/commands/npm-install-test.md b/docs/content/commands/npm-install-test.md
index 3dd860ea5c6f6..d27686e731ce1 100644
--- a/docs/content/commands/npm-install-test.md
+++ b/docs/content/commands/npm-install-test.md
@@ -11,16 +11,7 @@ description: Install package(s) and run tests
 <!-- see lib/commands/install-test.js -->
 
 ```bash
-npm install-test [<@scope>/]<pkg>
-npm install-test [<@scope>/]<pkg>@<tag>
-npm install-test [<@scope>/]<pkg>@<version>
-npm install-test [<@scope>/]<pkg>@<version range>
-npm install-test <alias>@npm:<name>
-npm install-test <folder>
-npm install-test <tarball file>
-npm install-test <tarball url>
-npm install-test <git:// url>
-npm install-test <github username>/<github project>
+npm install-test [<package-spec> ...]
 
 alias: it
 ```
diff --git a/docs/content/commands/npm-install.md b/docs/content/commands/npm-install.md
index 445772f0353a1..f05e532668fe2 100644
--- a/docs/content/commands/npm-install.md
+++ b/docs/content/commands/npm-install.md
@@ -11,16 +11,7 @@ description: Install a package
 <!-- see lib/commands/install.js -->
 
 ```bash
-npm install [<@scope>/]<pkg>
-npm install [<@scope>/]<pkg>@<tag>
-npm install [<@scope>/]<pkg>@<version>
-npm install [<@scope>/]<pkg>@<version range>
-npm install <alias>@npm:<name>
-npm install <folder>
-npm install <tarball file>
-npm install <tarball url>
-npm install <git:// url>
-npm install <github username>/<github project>
+npm install [<package-spec> ...]
 
 aliases: add, i, in, ins, inst, insta, instal, isnt, isnta, isntal, isntall
 ```
diff --git a/docs/content/commands/npm-link.md b/docs/content/commands/npm-link.md
index 975c807c38b34..8c1b422493bd5 100644
--- a/docs/content/commands/npm-link.md
+++ b/docs/content/commands/npm-link.md
@@ -11,8 +11,7 @@ description: Symlink a package folder
 <!-- see lib/commands/link.js -->
 
 ```bash
-npm link (in package dir)
-npm link [<@scope>/]<pkg>[@<version>]
+npm link [<package-spec>]
 
 alias: ln
 ```
@@ -29,11 +28,11 @@ test iteratively without having to continually rebuild.
 
 Package linking is a two-step process.
 
-First, `npm link` in a package folder will create a symlink in the global
-folder `{prefix}/lib/node_modules/<package>` that links to the package
-where the `npm link` command was executed. It will also link any bins in
-the package to `{prefix}/bin/{name}`.  Note that `npm link` uses the global
-prefix (see `npm prefix -g` for its value).
+First, `npm link` in a package folder with no arguments will create a
+symlink in the global folder `{prefix}/lib/node_modules/<package>` that
+links to the package where the `npm link` command was executed. It will
+also link any bins in the package to `{prefix}/bin/{name}`.  Note that
+`npm link` uses the global prefix (see `npm prefix -g` for its value).
 
 Next, in some other location, `npm link package-name` will create a
 symbolic link from globally-installed `package-name` to `node_modules/` of
@@ -399,6 +398,7 @@ symlink. This option has no effect on workspaces.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm developers](/using-npm/developers)
 * [package.json](/configuring-npm/package-json)
 * [npm install](/commands/npm-install)
diff --git a/docs/content/commands/npm-ls.md b/docs/content/commands/npm-ls.md
index ded8c0c0d26ef..a97c5168e6e0b 100644
--- a/docs/content/commands/npm-ls.md
+++ b/docs/content/commands/npm-ls.md
@@ -11,7 +11,7 @@ description: List installed packages
 <!-- see lib/commands/ls.js -->
 
 ```bash
-npm ls [[<@scope>/]<pkg> ...]
+npm ls <package-spec>
 
 alias: list
 ```
@@ -301,6 +301,7 @@ symlink. This option has no effect on workspaces.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm explain](/commands/npm-explain)
 * [npm config](/commands/npm-config)
 * [npmrc](/configuring-npm/npmrc)
diff --git a/docs/content/commands/npm-outdated.md b/docs/content/commands/npm-outdated.md
index 6fa026550e747..c4e07a0cd36f0 100644
--- a/docs/content/commands/npm-outdated.md
+++ b/docs/content/commands/npm-outdated.md
@@ -11,7 +11,7 @@ description: Check for outdated packages
 <!-- see lib/commands/outdated.js -->
 
 ```bash
-npm outdated [[<@scope>/]<pkg> ...]
+npm outdated [<package-spec> ...]
 ```
 
 <!-- automatically generated, do not edit manually -->
@@ -192,6 +192,7 @@ This value is not exported to the environment for child processes.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm update](/commands/npm-update)
 * [npm dist-tag](/commands/npm-dist-tag)
 * [npm registry](/using-npm/registry)
diff --git a/docs/content/commands/npm-owner.md b/docs/content/commands/npm-owner.md
index 72dfe6a22d01b..ebc29ef693939 100644
--- a/docs/content/commands/npm-owner.md
+++ b/docs/content/commands/npm-owner.md
@@ -11,9 +11,9 @@ description: Manage package owners
 <!-- see lib/commands/owner.js -->
 
 ```bash
-npm owner add <user> [<@scope>/]<pkg>
-npm owner rm <user> [<@scope>/]<pkg>
-npm owner ls [<@scope>/]<pkg>
+npm owner add <user> <package-spec>
+npm owner rm <user> <package-spec>
+npm owner ls <package-spec>
 
 alias: author
 ```
@@ -123,6 +123,7 @@ This value is not exported to the environment for child processes.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm profile](/commands/npm-profile)
 * [npm publish](/commands/npm-publish)
 * [npm registry](/using-npm/registry)
diff --git a/docs/content/commands/npm-pack.md b/docs/content/commands/npm-pack.md
index fa6c005e9d228..7921042eae8fe 100644
--- a/docs/content/commands/npm-pack.md
+++ b/docs/content/commands/npm-pack.md
@@ -11,7 +11,7 @@ description: Create a tarball from a package
 <!-- see lib/commands/pack.js -->
 
 ```bash
-npm pack [[<@scope>/]<pkg>...]
+npm pack <package-spec>
 ```
 
 <!-- automatically generated, do not edit manually -->
@@ -144,6 +144,7 @@ If no arguments are supplied, then npm packs the current package folder.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm-packlist package](http://npm.im/npm-packlist)
 * [npm cache](/commands/npm-cache)
 * [npm publish](/commands/npm-publish)
diff --git a/docs/content/commands/npm-publish.md b/docs/content/commands/npm-publish.md
index 2995f6bc81551..536d04988e684 100644
--- a/docs/content/commands/npm-publish.md
+++ b/docs/content/commands/npm-publish.md
@@ -11,7 +11,7 @@ description: Publish a package
 <!-- see lib/commands/publish.js -->
 
 ```bash
-npm publish [<folder>]
+npm publish <package-spec>
 ```
 
 <!-- automatically generated, do not edit manually -->
@@ -23,42 +23,26 @@ npm publish [<folder>]
 
 Publishes a package to the registry so that it can be installed by name.
 
-By default npm will publish to the public registry. This can be overridden
-by specifying a different default registry or using a
-[`scope`](/using-npm/scope) in the name (see
+By default npm will publish to the public registry. This can be
+overridden by specifying a different default registry or using a
+[`scope`](/using-npm/scope) in the name, combined with a
+scope-configured registry (see
 [`package.json`](/configuring-npm/package-json)).
 
-* `<folder>`: A folder containing a package.json file
 
-* `<tarball>`: A url or file path to a gzipped tar archive containing a
-  single folder with a package.json file inside.
+A `package` is interpreted the same way as other commands (like
+`npm install` and can be:
 
-* `[--tag <tag>]`: Registers the published package with the given tag, such
-  that `npm install <name>@<tag>` will install this version.  By default,
-  `npm publish` updates and `npm install` installs the `latest` tag. See
-  [`npm-dist-tag`](npm-dist-tag) for details about tags.
-
-* `[--access <public|restricted>]`: Tells the registry whether this package
-  should be published as public or restricted. Only applies to scoped
-  packages, which default to `restricted`.  If you don't have a paid
-  account, you must publish with `--access public` to publish scoped
-  packages.
-
-* `[--otp <otpcode>]`: If you have two-factor authentication enabled in
-  `auth-and-writes` mode then you can provide a code from your
-  authenticator with this. If you don't include this and you're running
-  from a TTY then you'll be prompted.
-
-* `[--dry-run]`: As of `npm@6`, does everything publish would do except
-  actually publishing to the registry. Reports the details of what would
-  have been published.
-
-* `[--workspaces]`: Enables workspace context while publishing. All
-  workspace packages will be published.
-
-* `[--workspace]`: Enables workspaces context and limits results to only
-  those specified by this config item.  Only the packages in the
-  workspaces given will be published.
+* a) a folder containing a program described by a
+  [`package.json`](/configuring-npm/package-json) file
+* b) a gzipped tarball containing (a)
+* c) a url that resolves to (b)
+* d) a `<name>@<version>` that is published on the registry (see
+  [`registry`](/using-npm/registry)) with (c)
+* e) a `<name>@<tag>` (see [`npm dist-tag`](/commands/npm-dist-tag)) that
+  points to (d)
+* f) a `<name>` that has a "latest" tag satisfying (e)
+* g) a `<git remote url>` that resolves to (a)
 
 The publish will fail if the package name and version combination already
 exists in the specified registry.
@@ -247,6 +231,7 @@ This value is not exported to the environment for child processes.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm-packlist package](http://npm.im/npm-packlist)
 * [npm registry](/using-npm/registry)
 * [npm scope](/using-npm/scope)
diff --git a/docs/content/commands/npm-rebuild.md b/docs/content/commands/npm-rebuild.md
index 52c368c8c513b..6a396421213d3 100644
--- a/docs/content/commands/npm-rebuild.md
+++ b/docs/content/commands/npm-rebuild.md
@@ -11,7 +11,7 @@ description: Rebuild a package
 <!-- see lib/commands/rebuild.js -->
 
 ```bash
-npm rebuild [[<@scope>/]<name>[@<version>] ...]
+npm rebuild [<package-spec>] ...]
 
 alias: rb
 ```
@@ -29,9 +29,8 @@ C++ addons with the new binary.  It is also useful when installing with
 `--ignore-scripts` and `--no-bin-links`, to explicitly choose which
 packages to build and/or link bins.
 
-If one or more package names (and optionally version ranges) are provided,
-then only packages with a name and version matching one of the specifiers
-will be rebuilt.
+If one or more package specs are provided, then only packages with a
+name and version matching one of the specifiers will be rebuilt.
 
 ### Configuration
 
@@ -178,4 +177,5 @@ symlink. This option has no effect on workspaces.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm install](/commands/npm-install)
diff --git a/docs/content/commands/npm-restart.md b/docs/content/commands/npm-restart.md
index f01cd014e7435..048bebb1659bd 100644
--- a/docs/content/commands/npm-restart.md
+++ b/docs/content/commands/npm-restart.md
@@ -69,7 +69,7 @@ will *not* run any pre- or post-scripts.
 * Type: null or String
 
 The shell to use for scripts run with the `npm exec`, `npm run` and `npm
-init <pkg>` commands.
+init <package-spec>` commands.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
diff --git a/docs/content/commands/npm-run-script.md b/docs/content/commands/npm-run-script.md
index 73c4b1c7a748a..d94040f1a215d 100644
--- a/docs/content/commands/npm-run-script.md
+++ b/docs/content/commands/npm-run-script.md
@@ -246,7 +246,7 @@ will *not* run any pre- or post-scripts.
 * Type: null or String
 
 The shell to use for scripts run with the `npm exec`, `npm run` and `npm
-init <pkg>` commands.
+init <package-spec>` commands.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
diff --git a/docs/content/commands/npm-star.md b/docs/content/commands/npm-star.md
index 00ef17a816b4a..3e81c6a55bbb0 100644
--- a/docs/content/commands/npm-star.md
+++ b/docs/content/commands/npm-star.md
@@ -11,7 +11,7 @@ description: Mark your favorite packages
 <!-- see lib/commands/star.js -->
 
 ```bash
-npm star [<pkg>...]
+npm star [<package-spec>...]
 ```
 
 <!-- automatically generated, do not edit manually -->
@@ -87,6 +87,7 @@ password, npm will prompt on the command line for one.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm unstar](/commands/npm-unstar)
 * [npm stars](/commands/npm-stars)
 * [npm view](/commands/npm-view)
diff --git a/docs/content/commands/npm-start.md b/docs/content/commands/npm-start.md
index 8dd874b3c7d29..148f92606d83f 100644
--- a/docs/content/commands/npm-start.md
+++ b/docs/content/commands/npm-start.md
@@ -80,7 +80,7 @@ will *not* run any pre- or post-scripts.
 * Type: null or String
 
 The shell to use for scripts run with the `npm exec`, `npm run` and `npm
-init <pkg>` commands.
+init <package-spec>` commands.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
diff --git a/docs/content/commands/npm-stop.md b/docs/content/commands/npm-stop.md
index 9a3a55cf3f20e..a3084e8432ba7 100644
--- a/docs/content/commands/npm-stop.md
+++ b/docs/content/commands/npm-stop.md
@@ -73,7 +73,7 @@ will *not* run any pre- or post-scripts.
 * Type: null or String
 
 The shell to use for scripts run with the `npm exec`, `npm run` and `npm
-init <pkg>` commands.
+init <package-spec>` commands.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
diff --git a/docs/content/commands/npm-test.md b/docs/content/commands/npm-test.md
index 8a343ab299b34..72bb899d0b916 100644
--- a/docs/content/commands/npm-test.md
+++ b/docs/content/commands/npm-test.md
@@ -70,7 +70,7 @@ will *not* run any pre- or post-scripts.
 * Type: null or String
 
 The shell to use for scripts run with the `npm exec`, `npm run` and `npm
-init <pkg>` commands.
+init <package-spec>` commands.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
diff --git a/docs/content/commands/npm-unpublish.md b/docs/content/commands/npm-unpublish.md
index a4c481ea5af7f..9ad99e72a5a8e 100644
--- a/docs/content/commands/npm-unpublish.md
+++ b/docs/content/commands/npm-unpublish.md
@@ -11,7 +11,7 @@ description: Remove a package from the registry
 <!-- see lib/commands/unpublish.js -->
 
 ```bash
-npm unpublish [<@scope>/]<pkg>[@<version>]
+npm unpublish [<package-spec>]
 ```
 
 <!-- automatically generated, do not edit manually -->
@@ -146,6 +146,7 @@ This value is not exported to the environment for child processes.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm deprecate](/commands/npm-deprecate)
 * [npm publish](/commands/npm-publish)
 * [npm registry](/using-npm/registry)
diff --git a/docs/content/commands/npm-unstar.md b/docs/content/commands/npm-unstar.md
index 76202190da8c3..636e1b6ac0a94 100644
--- a/docs/content/commands/npm-unstar.md
+++ b/docs/content/commands/npm-unstar.md
@@ -11,7 +11,7 @@ description: Remove an item from your favorite packages
 <!-- see lib/commands/unstar.js -->
 
 ```bash
-npm unstar [<pkg>...]
+npm unstar [<package-spec>...]
 ```
 
 <!-- automatically generated, do not edit manually -->
diff --git a/docs/content/commands/npm-view.md b/docs/content/commands/npm-view.md
index 0ef17d8adfb39..d9d1daac0cda7 100644
--- a/docs/content/commands/npm-view.md
+++ b/docs/content/commands/npm-view.md
@@ -11,7 +11,7 @@ description: View registry info
 <!-- see lib/commands/view.js -->
 
 ```bash
-npm view [<@scope>/]<pkg>[@<version>] [<field>[.subfield]...]
+npm view [<package-spec>] [<field>[.subfield]...]
 
 aliases: info, show, v
 ```
@@ -203,6 +203,7 @@ the field name.
 
 ### See Also
 
+* [package spec](/using-npm/package-spec)
 * [npm search](/commands/npm-search)
 * [npm registry](/using-npm/registry)
 * [npm config](/commands/npm-config)
diff --git a/docs/content/using-npm/config.md b/docs/content/using-npm/config.md
index 6ef854eb6e0ff..3fb431402669f 100644
--- a/docs/content/using-npm/config.md
+++ b/docs/content/using-npm/config.md
@@ -1518,7 +1518,7 @@ npm init --scope=@foo --yes
 * Type: null or String
 
 The shell to use for scripts run with the `npm exec`, `npm run` and `npm
-init <pkg>` commands.
+init <package-spec>` commands.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
diff --git a/docs/content/using-npm/package-spec.md b/docs/content/using-npm/package-spec.md
new file mode 100644
index 0000000000000..0d3741018f036
--- /dev/null
+++ b/docs/content/using-npm/package-spec.md
@@ -0,0 +1,106 @@
+---
+title: package-spec
+section: 7
+description: Package name specifier
+---
+
+
+### Description
+
+Commands like `npm install` and the dependency sections in the
+`package.json` use a package name specifier.  This can be many different
+things that all refer to a "package".  Examples include a package name,
+git url, tarball, or local directory.  These will generally be referred
+to as `<package-spec>` in the help output for the npm commands that use
+this package name specifier.
+
+### Package name
+
+* `[<@scope>/]<pkg>`
+* `[<@scope>/]<pkg>@<tag>`
+* `[<@scope>/]<pkg>@<version>`
+* `[<@scope>/]<pkg>@<version range>`
+
+Refers to a package by name, with or without a scope, and optionally
+tag, version, or version range.  This is typically used in combination
+with the [registry](/using-npm/config#registry) config to refer to a
+package in a registry.
+
+Examples:
+* `npm`
+* `@npmcli/arborist`
+* `@npmcli/arborist@latest`
+* `npm@6.13.1`
+* `npm@^4.0.0`
+
+### Aliases
+
+* `<alias>@npm:<name>`
+
+Primarily used by commands like `npm install` and in the dependency
+sections in the `package.json`, this refers to a package by an alias.
+The `<alias>` is the name of the package as it is reified in the
+`node_modules` folder, and the `<name>` refers to a package name as
+found in the configured registry.
+
+See `Package name` above for more info on referring to a package by
+name, and [registry](/using-npm/config#registry) for configuring which
+registry is used when referring to a package by name.
+
+Examples:
+* `semver:@npm:@npmcli/semver-with-patch`
+* `semver:@npm:semver@7.2.2`
+* `semver:@npm:semver@legacy`
+
+### Folders
+
+* `<folder>`
+
+This refers to a package on the local filesystem.  Specifically this is
+a folder with a `package.json` file in it.  This *should* always be
+prefixed with a `/` or `./` (or your OS equivalent) to reduce confusion.
+npm currently will parse a string with more than one `/` in it as a
+folder, but this is legacy behavior that may be removed in a future
+version.
+
+Examples:
+
+* `./my-package`
+* `/opt/npm/my-package`
+
+### Tarballs
+
+* `<tarball file>`
+* `<tarball url>`
+
+Examples:
+
+* `./my-package.tgz`
+* `https://registry.npmjs.org/semver/-/semver-1.0.0.tgz`
+
+Refers to a package in a tarball format, either on the local filesystem
+or remotely via url.  This is the format that packages exist in when
+uploaded to a registry.
+
+### git urls
+
+* `<git:// url>`
+* `<github username>/<github project>`
+
+Refers to a package in a git repo.  This can be a full git url, git
+shorthand, or a username/package on GitHub.  You can specify a
+git tag, branch, or other git ref by appending `#ref`.
+
+Examples:
+
+* `https://github.com/npm/cli.git`
+* `git@github.com:npm/cli.git`
+* `git+ssh://git@github.com/npm/cli#v6.0.0`
+* `github:npm/cli#HEAD`
+* `npm/cli#c12ea07`
+
+### See also
+
+[npm-package-arg](https://npm.im/npm-package-arg)
+[scope](/using-npm/scope)
+[config](/using-npm/config)
diff --git a/docs/nav.yml b/docs/nav.yml
index a82847fc39760..bc39b969eba40 100644
--- a/docs/nav.yml
+++ b/docs/nav.yml
@@ -232,6 +232,9 @@
   - title: Registry
     url: /using-npm/registry
     description: The JavaScript Package Registry
+  - title: Package spec
+    url: /using-npm/package-spec
+    description: Package name specifier
   - title: Config
     url: /using-npm/config
     description: About npm configuration
diff --git a/lib/commands/cache.js b/lib/commands/cache.js
index 862f346adb436..bc52889c0006f 100644
--- a/lib/commands/cache.js
+++ b/lib/commands/cache.js
@@ -68,11 +68,7 @@ class Cache extends BaseCommand {
   static name = 'cache'
   static params = ['cache']
   static usage = [
-    'add <tarball file>',
-    'add <folder>',
-    'add <tarball url>',
-    'add <git url>',
-    'add <name>@<version>',
+    'add <package-spec>',
     'clean [<key>]',
     'ls [<name>@<version>]',
     'verify',
diff --git a/lib/commands/deprecate.js b/lib/commands/deprecate.js
index 0ae88f1921f56..862c214dbe592 100644
--- a/lib/commands/deprecate.js
+++ b/lib/commands/deprecate.js
@@ -9,7 +9,7 @@ const BaseCommand = require('../base-command.js')
 class Deprecate extends BaseCommand {
   static description = 'Deprecate a version of a package'
   static name = 'deprecate'
-  static usage = ['<pkg>[@<version>] <message>']
+  static usage = ['<package-spec> <message>']
   static params = [
     'registry',
     'otp',
diff --git a/lib/commands/dist-tag.js b/lib/commands/dist-tag.js
index a207e422cb53c..e74a3f1d435c9 100644
--- a/lib/commands/dist-tag.js
+++ b/lib/commands/dist-tag.js
@@ -12,9 +12,9 @@ class DistTag extends BaseCommand {
   static params = ['workspace', 'workspaces', 'include-workspace-root']
   static name = 'dist-tag'
   static usage = [
-    'add <pkg>@<version> [<tag>]',
-    'rm <pkg> <tag>',
-    'ls [<pkg>]',
+    'add <package-spec (with version)> [<tag>]',
+    'rm <package-spec> <tag>',
+    'ls [<package-spec>]',
   ]
 
   static ignoreImplicitWorkspace = false
@@ -90,7 +90,7 @@ class DistTag extends BaseCommand {
     log.verbose('dist-tag add', defaultTag, 'to', spec.name + '@' + version)
 
     if (!spec.name || !version || !defaultTag) {
-      throw this.usageError()
+      throw this.usageError('must provide a spec with a name and version, and a tag to add')
     }
 
     const t = defaultTag.trim()
diff --git a/lib/commands/explain.js b/lib/commands/explain.js
index ca6ee7540bc91..c0ef04548a4ed 100644
--- a/lib/commands/explain.js
+++ b/lib/commands/explain.js
@@ -10,7 +10,7 @@ const ArboristWorkspaceCmd = require('../arborist-cmd.js')
 class Explain extends ArboristWorkspaceCmd {
   static description = 'Explain installed packages'
   static name = 'explain'
-  static usage = ['<folder | specifier>']
+  static usage = ['<package-spec>']
   static params = [
     'json',
     'workspace',
diff --git a/lib/commands/fund.js b/lib/commands/fund.js
index 09ca81653b0eb..9690cbc32e079 100644
--- a/lib/commands/fund.js
+++ b/lib/commands/fund.js
@@ -20,7 +20,7 @@ class Fund extends ArboristWorkspaceCmd {
   static description = 'Retrieve funding information'
   static name = 'fund'
   static params = ['json', 'browser', 'unicode', 'workspace', 'which']
-  static usage = ['[[<@scope>/]<pkg>]']
+  static usage = ['[<package-spec>]']
 
   // TODO
   /* istanbul ignore next */
diff --git a/lib/commands/init.js b/lib/commands/init.js
index 4c299e65137be..b8b6bd5d53e08 100644
--- a/lib/commands/init.js
+++ b/lib/commands/init.js
@@ -18,6 +18,7 @@ class Init extends BaseCommand {
   static params = [
     'yes',
     'force',
+    'scope',
     'workspace',
     'workspaces',
     'workspaces-update',
@@ -26,9 +27,8 @@ class Init extends BaseCommand {
 
   static name = 'init'
   static usage = [
-    '[--force|-f|--yes|-y|--scope]',
+    '<package-spec> (same as `npx <package-spec>)',
     '<@scope> (same as `npx <@scope>/create`)',
-    '[<@scope>/]<name> (same as `npx [<@scope>/]create-<name>`)',
   ]
 
   static ignoreImplicitWorkspace = false
diff --git a/lib/commands/install.js b/lib/commands/install.js
index 4cda36448317f..ecc0727a2ef7c 100644
--- a/lib/commands/install.js
+++ b/lib/commands/install.js
@@ -34,18 +34,7 @@ class Install extends ArboristWorkspaceCmd {
     ...super.params,
   ]
 
-  static usage = [
-    '[<@scope>/]<pkg>',
-    '[<@scope>/]<pkg>@<tag>',
-    '[<@scope>/]<pkg>@<version>',
-    '[<@scope>/]<pkg>@<version range>',
-    '<alias>@npm:<name>',
-    '<folder>',
-    '<tarball file>',
-    '<tarball url>',
-    '<git:// url>',
-    '<github username>/<github project>',
-  ]
+  static usage = ['[<package-spec> ...]']
 
   async completion (opts) {
     const { partialWord } = opts
diff --git a/lib/commands/link.js b/lib/commands/link.js
index 80a60d36e324e..b0b889ea787fd 100644
--- a/lib/commands/link.js
+++ b/lib/commands/link.js
@@ -15,8 +15,7 @@ class Link extends ArboristWorkspaceCmd {
   static description = 'Symlink a package folder'
   static name = 'link'
   static usage = [
-    '(in package dir)',
-    '[<@scope>/]<pkg>[@<version>]',
+    '[<package-spec>]',
   ]
 
   static params = [
diff --git a/lib/commands/ls.js b/lib/commands/ls.js
index cfd9cb5a5051c..d3932072b7d34 100644
--- a/lib/commands/ls.js
+++ b/lib/commands/ls.js
@@ -27,7 +27,7 @@ const localeCompare = require('@isaacs/string-locale-compare')('en')
 class LS extends ArboristWorkspaceCmd {
   static description = 'List installed packages'
   static name = 'ls'
-  static usage = ['[[<@scope>/]<pkg> ...]']
+  static usage = ['<package-spec>']
   static params = [
     'all',
     'json',
diff --git a/lib/commands/outdated.js b/lib/commands/outdated.js
index 081e75a2c61d3..042b776f71e0d 100644
--- a/lib/commands/outdated.js
+++ b/lib/commands/outdated.js
@@ -15,7 +15,7 @@ const ArboristWorkspaceCmd = require('../arborist-cmd.js')
 class Outdated extends ArboristWorkspaceCmd {
   static description = 'Check for outdated packages'
   static name = 'outdated'
-  static usage = ['[[<@scope>/]<pkg> ...]']
+  static usage = ['[<package-spec> ...]']
   static params = [
     'all',
     'json',
diff --git a/lib/commands/owner.js b/lib/commands/owner.js
index 4797e9c7ec84b..732bb40a30050 100644
--- a/lib/commands/owner.js
+++ b/lib/commands/owner.js
@@ -27,9 +27,9 @@ class Owner extends BaseCommand {
   ]
 
   static usage = [
-    'add <user> [<@scope>/]<pkg>',
-    'rm <user> [<@scope>/]<pkg>',
-    'ls [<@scope>/]<pkg>',
+    'add <user> <package-spec>',
+    'rm <user> <package-spec>',
+    'ls <package-spec>',
   ]
 
   static ignoreImplicitWorkspace = false
diff --git a/lib/commands/pack.js b/lib/commands/pack.js
index 8190ceecaf94b..c6a74804642f6 100644
--- a/lib/commands/pack.js
+++ b/lib/commands/pack.js
@@ -17,7 +17,7 @@ class Pack extends BaseCommand {
     'include-workspace-root',
   ]
 
-  static usage = ['[[<@scope>/]<pkg>...]']
+  static usage = ['<package-spec>']
   static ignoreImplicitWorkspace = false
 
   async exec (args) {
diff --git a/lib/commands/publish.js b/lib/commands/publish.js
index da6437fa9c58f..579f5d6e74e67 100644
--- a/lib/commands/publish.js
+++ b/lib/commands/publish.js
@@ -37,7 +37,7 @@ class Publish extends BaseCommand {
     'include-workspace-root',
   ]
 
-  static usage = ['[<folder>]']
+  static usage = ['<package-spec>']
   static ignoreImplicitWorkspace = false
 
   async exec (args) {
diff --git a/lib/commands/rebuild.js b/lib/commands/rebuild.js
index 3e6046d8df22b..d06313ce483a9 100644
--- a/lib/commands/rebuild.js
+++ b/lib/commands/rebuild.js
@@ -16,7 +16,7 @@ class Rebuild extends ArboristWorkspaceCmd {
     ...super.params,
   ]
 
-  static usage = ['[[<@scope>/]<name>[@<version>] ...]']
+  static usage = ['[<package-spec>] ...]']
 
   // TODO
   /* istanbul ignore next */
diff --git a/lib/commands/star.js b/lib/commands/star.js
index 7b76be3c1632d..20039bf893811 100644
--- a/lib/commands/star.js
+++ b/lib/commands/star.js
@@ -7,7 +7,7 @@ const BaseCommand = require('../base-command.js')
 class Star extends BaseCommand {
   static description = 'Mark your favorite packages'
   static name = 'star'
-  static usage = ['[<pkg>...]']
+  static usage = ['[<package-spec>...]']
   static params = [
     'registry',
     'unicode',
diff --git a/lib/commands/unpublish.js b/lib/commands/unpublish.js
index f27be2e41c107..ab929d98cadfa 100644
--- a/lib/commands/unpublish.js
+++ b/lib/commands/unpublish.js
@@ -20,7 +20,7 @@ class Unpublish extends BaseCommand {
   static description = 'Remove a package from the registry'
   static name = 'unpublish'
   static params = ['dry-run', 'force', 'workspace', 'workspaces']
-  static usage = ['[<@scope>/]<pkg>[@<version>]']
+  static usage = ['[<package-spec>]']
   static ignoreImplicitWorkspace = false
 
   async getKeysOfVersions (name, opts) {
diff --git a/lib/commands/view.js b/lib/commands/view.js
index efb298a03bc35..db5d99b685558 100644
--- a/lib/commands/view.js
+++ b/lib/commands/view.js
@@ -33,7 +33,7 @@ class View extends BaseCommand {
 
   static ignoreImplicitWorkspace = false
 
-  static usage = ['[<@scope>/]<pkg>[@<version>] [<field>[.subfield]...]']
+  static usage = ['[<package-spec>] [<field>[.subfield]...]']
 
   async completion (opts) {
     if (opts.conf.argv.remain.length <= 2) {
diff --git a/lib/utils/config/definitions.js b/lib/utils/config/definitions.js
index 4c77e375c5ccf..6b35e7d4d05b4 100644
--- a/lib/utils/config/definitions.js
+++ b/lib/utils/config/definitions.js
@@ -535,7 +535,7 @@ define('dev', {
 
 define('diff', {
   default: [],
-  hint: '<pkg-name|spec|version>',
+  hint: '<package-spec>',
   type: [String, Array],
   description: `
     Define arguments to compare in \`npm diff\`.
@@ -1458,7 +1458,7 @@ define('otp', {
 
 define('package', {
   default: [],
-  hint: '<pkg>[@<version>]',
+  hint: '<package-spec>',
   type: [String, Array],
   description: `
     The package to install for [\`npm exec\`](/commands/npm-exec)
@@ -1867,7 +1867,7 @@ define('script-shell', {
   type: [null, String],
   description: `
     The shell to use for scripts run with the \`npm exec\`,
-    \`npm run\` and \`npm init <pkg>\` commands.
+    \`npm run\` and \`npm init <package-spec>\` commands.
   `,
   flatten (key, obj, flatOptions) {
     flatOptions.scriptShell = obj[key] || undefined
diff --git a/tap-snapshots/test/lib/load-all-commands.js.test.cjs b/tap-snapshots/test/lib/load-all-commands.js.test.cjs
index 802fa8de93516..13a3b06fe33d6 100644
--- a/tap-snapshots/test/lib/load-all-commands.js.test.cjs
+++ b/tap-snapshots/test/lib/load-all-commands.js.test.cjs
@@ -98,11 +98,7 @@ exports[`test/lib/load-all-commands.js TAP load each command cache > must match
 Manipulates packages cache
 
 Usage:
-npm cache add <tarball file>
-npm cache add <folder>
-npm cache add <tarball url>
-npm cache add <git url>
-npm cache add <name>@<version>
+npm cache add <package-spec>
 npm cache clean [<key>]
 npm cache ls [<name>@<version>]
 npm cache verify
@@ -178,7 +174,7 @@ exports[`test/lib/load-all-commands.js TAP load each command deprecate > must ma
 Deprecate a version of a package
 
 Usage:
-npm deprecate <pkg>[@<version>] <message>
+npm deprecate <package-spec> <message>
 
 Options:
 [--registry <registry>] [--otp <otp>]
@@ -193,10 +189,10 @@ Usage:
 npm diff [...<paths>]
 
 Options:
-[--diff <pkg-name|spec|version> [--diff <pkg-name|spec|version> ...]]
-[--diff-name-only] [--diff-unified <number>] [--diff-ignore-all-space]
-[--diff-no-prefix] [--diff-src-prefix <path>] [--diff-dst-prefix <path>]
-[--diff-text] [-g|--global] [--tag <tag>]
+[--diff <package-spec> [--diff <package-spec> ...]] [--diff-name-only]
+[--diff-unified <number>] [--diff-ignore-all-space] [--diff-no-prefix]
+[--diff-src-prefix <path>] [--diff-dst-prefix <path>] [--diff-text] [-g|--global]
+[--tag <tag>]
 [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
 [-ws|--workspaces] [--include-workspace-root]
 
@@ -207,9 +203,9 @@ exports[`test/lib/load-all-commands.js TAP load each command dist-tag > must mat
 Modify package distribution tags
 
 Usage:
-npm dist-tag add <pkg>@<version> [<tag>]
-npm dist-tag rm <pkg> <tag>
-npm dist-tag ls [<pkg>]
+npm dist-tag add <package-spec (with version)> [<tag>]
+npm dist-tag rm <package-spec> <tag>
+npm dist-tag ls [<package-spec>]
 
 Options:
 [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
@@ -270,8 +266,7 @@ npm exec -c '<cmd> [args...]'
 npm exec --package=foo -c '<cmd> [args...]'
 
 Options:
-[--package <pkg>[@<version>] [--package <pkg>[@<version>] ...]]
-[-c|--call <call>]
+[--package <package-spec> [--package <package-spec> ...]] [-c|--call <call>]
 [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
 [-ws|--workspaces] [--include-workspace-root]
 
@@ -284,7 +279,7 @@ exports[`test/lib/load-all-commands.js TAP load each command explain > must matc
 Explain installed packages
 
 Usage:
-npm explain <folder | specifier>
+npm explain <package-spec>
 
 Options:
 [--json] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
@@ -326,7 +321,7 @@ exports[`test/lib/load-all-commands.js TAP load each command fund > must match s
 Retrieve funding information
 
 Usage:
-npm fund [[<@scope>/]<pkg>]
+npm fund [<package-spec>]
 
 Options:
 [--json] [--no-browser|--browser <browser>] [--unicode]
@@ -390,12 +385,11 @@ exports[`test/lib/load-all-commands.js TAP load each command init > must match s
 Create a package.json file
 
 Usage:
-npm init [--force|-f|--yes|-y|--scope]
+npm init <package-spec> (same as \`npx <package-spec>)
 npm init <@scope> (same as \`npx <@scope>/create\`)
-npm init [<@scope>/]<name> (same as \`npx [<@scope>/]create-<name>\`)
 
 Options:
-[-y|--yes] [-f|--force]
+[-y|--yes] [-f|--force] [--scope <@scope>]
 [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
 [-ws|--workspaces] [--no-workspaces-update] [--include-workspace-root]
 
@@ -408,16 +402,7 @@ exports[`test/lib/load-all-commands.js TAP load each command install > must matc
 Install a package
 
 Usage:
-npm install [<@scope>/]<pkg>
-npm install [<@scope>/]<pkg>@<tag>
-npm install [<@scope>/]<pkg>@<version>
-npm install [<@scope>/]<pkg>@<version range>
-npm install <alias>@npm:<name>
-npm install <folder>
-npm install <tarball file>
-npm install <tarball url>
-npm install <git:// url>
-npm install <github username>/<github project>
+npm install [<package-spec> ...]
 
 Options:
 [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle]
@@ -452,16 +437,7 @@ exports[`test/lib/load-all-commands.js TAP load each command install-test > must
 Install package(s) and run tests
 
 Usage:
-npm install-test [<@scope>/]<pkg>
-npm install-test [<@scope>/]<pkg>@<tag>
-npm install-test [<@scope>/]<pkg>@<version>
-npm install-test [<@scope>/]<pkg>@<version range>
-npm install-test <alias>@npm:<name>
-npm install-test <folder>
-npm install-test <tarball file>
-npm install-test <tarball url>
-npm install-test <git:// url>
-npm install-test <github username>/<github project>
+npm install-test [<package-spec> ...]
 
 Options:
 [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle]
@@ -481,8 +457,7 @@ exports[`test/lib/load-all-commands.js TAP load each command link > must match s
 Symlink a package folder
 
 Usage:
-npm link (in package dir)
-npm link [<@scope>/]<pkg>[@<version>]
+npm link [<package-spec>]
 
 Options:
 [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle]
@@ -547,7 +522,7 @@ exports[`test/lib/load-all-commands.js TAP load each command ls > must match sna
 List installed packages
 
 Usage:
-npm ls [[<@scope>/]<pkg> ...]
+npm ls <package-spec>
 
 Options:
 [-a|--all] [--json] [-l|--long] [-p|--parseable] [-g|--global] [--depth <depth>]
@@ -581,7 +556,7 @@ exports[`test/lib/load-all-commands.js TAP load each command outdated > must mat
 Check for outdated packages
 
 Usage:
-npm outdated [[<@scope>/]<pkg> ...]
+npm outdated [<package-spec> ...]
 
 Options:
 [-a|--all] [--json] [-l|--long] [-p|--parseable] [-g|--global]
@@ -594,9 +569,9 @@ exports[`test/lib/load-all-commands.js TAP load each command owner > must match
 Manage package owners
 
 Usage:
-npm owner add <user> [<@scope>/]<pkg>
-npm owner rm <user> [<@scope>/]<pkg>
-npm owner ls [<@scope>/]<pkg>
+npm owner add <user> <package-spec>
+npm owner rm <user> <package-spec>
+npm owner ls <package-spec>
 
 Options:
 [--registry <registry>] [--otp <otp>]
@@ -612,7 +587,7 @@ exports[`test/lib/load-all-commands.js TAP load each command pack > must match s
 Create a tarball from a package
 
 Usage:
-npm pack [[<@scope>/]<pkg>...]
+npm pack <package-spec>
 
 Options:
 [--dry-run] [--json] [--pack-destination <pack-destination>]
@@ -698,7 +673,7 @@ exports[`test/lib/load-all-commands.js TAP load each command publish > must matc
 Publish a package
 
 Usage:
-npm publish [<folder>]
+npm publish <package-spec>
 
 Options:
 [--tag <tag>] [--access <restricted|public>] [--dry-run] [--otp <otp>]
@@ -712,7 +687,7 @@ exports[`test/lib/load-all-commands.js TAP load each command rebuild > must matc
 Rebuild a package
 
 Usage:
-npm rebuild [[<@scope>/]<name>[@<version>] ...]
+npm rebuild [<package-spec>] ...]
 
 Options:
 [-g|--global] [--no-bin-links] [--foreground-scripts] [--ignore-scripts]
@@ -829,7 +804,7 @@ exports[`test/lib/load-all-commands.js TAP load each command star > must match s
 Mark your favorite packages
 
 Usage:
-npm star [<pkg>...]
+npm star [<package-spec>...]
 
 Options:
 [--registry <registry>] [--unicode] [--otp <otp>]
@@ -938,7 +913,7 @@ exports[`test/lib/load-all-commands.js TAP load each command unpublish > must ma
 Remove a package from the registry
 
 Usage:
-npm unpublish [<@scope>/]<pkg>[@<version>]
+npm unpublish [<package-spec>]
 
 Options:
 [--dry-run] [-f|--force]
@@ -952,7 +927,7 @@ exports[`test/lib/load-all-commands.js TAP load each command unstar > must match
 Remove an item from your favorite packages
 
 Usage:
-npm unstar [<pkg>...]
+npm unstar [<package-spec>...]
 
 Options:
 [--registry <registry>] [--unicode] [--otp <otp>]
@@ -1001,7 +976,7 @@ exports[`test/lib/load-all-commands.js TAP load each command view > must match s
 View registry info
 
 Usage:
-npm view [<@scope>/]<pkg>[@<version>] [<field>[.subfield]...]
+npm view [<package-spec>] [<field>[.subfield]...]
 
 Options:
 [--json] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
diff --git a/tap-snapshots/test/lib/npm.js.test.cjs b/tap-snapshots/test/lib/npm.js.test.cjs
index b2443e8949959..2cf4f53ecab8e 100644
--- a/tap-snapshots/test/lib/npm.js.test.cjs
+++ b/tap-snapshots/test/lib/npm.js.test.cjs
@@ -238,11 +238,7 @@ All commands:
     cache           Manipulates packages cache
                     
                     Usage:
-                    npm cache add <tarball file>
-                    npm cache add <folder>
-                    npm cache add <tarball url>
-                    npm cache add <git url>
-                    npm cache add <name>@<version>
+                    npm cache add <package-spec>
                     npm cache clean [<key>]
                     npm cache ls [<name>@<version>]
                     npm cache verify
@@ -308,7 +304,7 @@ All commands:
     deprecate       Deprecate a version of a package
                     
                     Usage:
-                    npm deprecate <pkg>[@<version>] <message>
+                    npm deprecate <package-spec> <message>
                     
                     Options:
                     [--registry <registry>] [--otp <otp>]
@@ -321,10 +317,10 @@ All commands:
                     npm diff [...<paths>]
                     
                     Options:
-                    [--diff <pkg-name|spec|version> [--diff <pkg-name|spec|version> ...]]
-                    [--diff-name-only] [--diff-unified <number>] [--diff-ignore-all-space]
-                    [--diff-no-prefix] [--diff-src-prefix <path>] [--diff-dst-prefix <path>]
-                    [--diff-text] [-g|--global] [--tag <tag>]
+                    [--diff <package-spec> [--diff <package-spec> ...]] [--diff-name-only]
+                    [--diff-unified <number>] [--diff-ignore-all-space] [--diff-no-prefix]
+                    [--diff-src-prefix <path>] [--diff-dst-prefix <path>] [--diff-text] [-g|--global]
+                    [--tag <tag>]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
                     [-ws|--workspaces] [--include-workspace-root]
                     
@@ -333,9 +329,9 @@ All commands:
     dist-tag        Modify package distribution tags
                     
                     Usage:
-                    npm dist-tag add <pkg>@<version> [<tag>]
-                    npm dist-tag rm <pkg> <tag>
-                    npm dist-tag ls [<pkg>]
+                    npm dist-tag add <package-spec (with version)> [<tag>]
+                    npm dist-tag rm <package-spec> <tag>
+                    npm dist-tag ls [<package-spec>]
                     
                     Options:
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
@@ -388,8 +384,7 @@ All commands:
                     npm exec --package=foo -c '<cmd> [args...]'
                     
                     Options:
-                    [--package <pkg>[@<version>] [--package <pkg>[@<version>] ...]]
-                    [-c|--call <call>]
+                    [--package <package-spec> [--package <package-spec> ...]] [-c|--call <call>]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
                     [-ws|--workspaces] [--include-workspace-root]
                     
@@ -400,7 +395,7 @@ All commands:
     explain         Explain installed packages
                     
                     Usage:
-                    npm explain <folder | specifier>
+                    npm explain <package-spec>
                     
                     Options:
                     [--json] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
@@ -436,7 +431,7 @@ All commands:
     fund            Retrieve funding information
                     
                     Usage:
-                    npm fund [[<@scope>/]<pkg>]
+                    npm fund [<package-spec>]
                     
                     Options:
                     [--json] [--no-browser|--browser <browser>] [--unicode]
@@ -480,12 +475,11 @@ All commands:
     init            Create a package.json file
                     
                     Usage:
-                    npm init [--force|-f|--yes|-y|--scope]
+                    npm init <package-spec> (same as \`npx <package-spec>)
                     npm init <@scope> (same as \`npx <@scope>/create\`)
-                    npm init [<@scope>/]<name> (same as \`npx [<@scope>/]create-<name>\`)
                     
                     Options:
-                    [-y|--yes] [-f|--force]
+                    [-y|--yes] [-f|--force] [--scope <@scope>]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
                     [-ws|--workspaces] [--no-workspaces-update] [--include-workspace-root]
                     
@@ -496,16 +490,7 @@ All commands:
     install         Install a package
                     
                     Usage:
-                    npm install [<@scope>/]<pkg>
-                    npm install [<@scope>/]<pkg>@<tag>
-                    npm install [<@scope>/]<pkg>@<version>
-                    npm install [<@scope>/]<pkg>@<version range>
-                    npm install <alias>@npm:<name>
-                    npm install <folder>
-                    npm install <tarball file>
-                    npm install <tarball url>
-                    npm install <git:// url>
-                    npm install <github username>/<github project>
+                    npm install [<package-spec> ...]
                     
                     Options:
                     [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle]
@@ -536,16 +521,7 @@ All commands:
     install-test    Install package(s) and run tests
                     
                     Usage:
-                    npm install-test [<@scope>/]<pkg>
-                    npm install-test [<@scope>/]<pkg>@<tag>
-                    npm install-test [<@scope>/]<pkg>@<version>
-                    npm install-test [<@scope>/]<pkg>@<version range>
-                    npm install-test <alias>@npm:<name>
-                    npm install-test <folder>
-                    npm install-test <tarball file>
-                    npm install-test <tarball url>
-                    npm install-test <git:// url>
-                    npm install-test <github username>/<github project>
+                    npm install-test [<package-spec> ...]
                     
                     Options:
                     [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle]
@@ -563,8 +539,7 @@ All commands:
     link            Symlink a package folder
                     
                     Usage:
-                    npm link (in package dir)
-                    npm link [<@scope>/]<pkg>[@<version>]
+                    npm link [<package-spec>]
                     
                     Options:
                     [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle]
@@ -621,7 +596,7 @@ All commands:
     ls              List installed packages
                     
                     Usage:
-                    npm ls [[<@scope>/]<pkg> ...]
+                    npm ls <package-spec>
                     
                     Options:
                     [-a|--all] [--json] [-l|--long] [-p|--parseable] [-g|--global] [--depth <depth>]
@@ -651,7 +626,7 @@ All commands:
     outdated        Check for outdated packages
                     
                     Usage:
-                    npm outdated [[<@scope>/]<pkg> ...]
+                    npm outdated [<package-spec> ...]
                     
                     Options:
                     [-a|--all] [--json] [-l|--long] [-p|--parseable] [-g|--global]
@@ -662,9 +637,9 @@ All commands:
     owner           Manage package owners
                     
                     Usage:
-                    npm owner add <user> [<@scope>/]<pkg>
-                    npm owner rm <user> [<@scope>/]<pkg>
-                    npm owner ls [<@scope>/]<pkg>
+                    npm owner add <user> <package-spec>
+                    npm owner rm <user> <package-spec>
+                    npm owner ls <package-spec>
                     
                     Options:
                     [--registry <registry>] [--otp <otp>]
@@ -678,7 +653,7 @@ All commands:
     pack            Create a tarball from a package
                     
                     Usage:
-                    npm pack [[<@scope>/]<pkg>...]
+                    npm pack <package-spec>
                     
                     Options:
                     [--dry-run] [--json] [--pack-destination <pack-destination>]
@@ -752,7 +727,7 @@ All commands:
     publish         Publish a package
                     
                     Usage:
-                    npm publish [<folder>]
+                    npm publish <package-spec>
                     
                     Options:
                     [--tag <tag>] [--access <restricted|public>] [--dry-run] [--otp <otp>]
@@ -764,7 +739,7 @@ All commands:
     rebuild         Rebuild a package
                     
                     Usage:
-                    npm rebuild [[<@scope>/]<name>[@<version>] ...]
+                    npm rebuild [<package-spec>] ...]
                     
                     Options:
                     [-g|--global] [--no-bin-links] [--foreground-scripts] [--ignore-scripts]
@@ -863,7 +838,7 @@ All commands:
     star            Mark your favorite packages
                     
                     Usage:
-                    npm star [<pkg>...]
+                    npm star [<package-spec>...]
                     
                     Options:
                     [--registry <registry>] [--unicode] [--otp <otp>]
@@ -956,7 +931,7 @@ All commands:
     unpublish       Remove a package from the registry
                     
                     Usage:
-                    npm unpublish [<@scope>/]<pkg>[@<version>]
+                    npm unpublish [<package-spec>]
                     
                     Options:
                     [--dry-run] [-f|--force]
@@ -968,7 +943,7 @@ All commands:
     unstar          Remove an item from your favorite packages
                     
                     Usage:
-                    npm unstar [<pkg>...]
+                    npm unstar [<package-spec>...]
                     
                     Options:
                     [--registry <registry>] [--unicode] [--otp <otp>]
@@ -1011,7 +986,7 @@ All commands:
     view            View registry info
                     
                     Usage:
-                    npm view [<@scope>/]<pkg>[@<version>] [<field>[.subfield]...]
+                    npm view [<package-spec>] [<field>[.subfield]...]
                     
                     Options:
                     [--json] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
diff --git a/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs b/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs
index 33d6e4fb7a00f..19909d8c5b35d 100644
--- a/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs
+++ b/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs
@@ -1591,7 +1591,7 @@ exports[`test/lib/utils/config/definitions.js TAP > config description for scrip
 * Type: null or String
 
 The shell to use for scripts run with the \`npm exec\`, \`npm run\` and \`npm
-init <pkg>\` commands.
+init <package-spec>\` commands.
 `
 
 exports[`test/lib/utils/config/definitions.js TAP > config description for searchexclude 1`] = `
diff --git a/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs b/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs
index 77f2c876841ed..9d95aa9528bd8 100644
--- a/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs
+++ b/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs
@@ -1391,7 +1391,7 @@ npm init --scope=@foo --yes
 * Type: null or String
 
 The shell to use for scripts run with the \`npm exec\`, \`npm run\` and \`npm
-init <pkg>\` commands.
+init <package-spec>\` commands.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->