From 58963edeee4a974611f4147c0b6dc7c1b12bfc53 Mon Sep 17 00:00:00 2001
From: Wassim Chegham <github@wassim.dev>
Date: Fri, 18 Feb 2022 09:08:47 +0100
Subject: [PATCH 1/7] docs: auto-generate synopsis sections

Fixes #4189
---
 docs/content/commands/npm-init.md |  4 ++++
 scripts/config-doc-command.js     | 26 +++++++++++++++++++++-----
 2 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/docs/content/commands/npm-init.md b/docs/content/commands/npm-init.md
index a608061a96d8d..7a96ccc389627 100644
--- a/docs/content/commands/npm-init.md
+++ b/docs/content/commands/npm-init.md
@@ -6,6 +6,8 @@ description: Create a package.json file
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+
 ```bash
 npm init [--yes|-y|--scope]
 npm init <@scope> (same as `npm exec <@scope>/create`)
@@ -13,6 +15,8 @@ npm init [<@scope>/]<name> (same as `npm exec [<@scope>/]create-<name>`)
 npm init [-w <dir>] [args...]
 ```
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 `npm init <initializer>` can be used to set up a new or existing npm
diff --git a/scripts/config-doc-command.js b/scripts/config-doc-command.js
index 9db026f304281..9fa3f83d01490 100644
--- a/scripts/config-doc-command.js
+++ b/scripts/config-doc-command.js
@@ -6,16 +6,18 @@ const configDoc = process.argv[2]
 const commandFile = process.argv[3]
 
 // Note: commands without params skip this whole process.
-const { params } = require(resolve(commandFile))
+const { params, usage } = require(resolve(commandFile))
 
-const describeAll = () =>
-  params.map(name => definitions[name].describe()).join(
+const describeAll = (content) =>
+  content.map(name => definitions[name].describe()).join(
     '\n\n<!-- automatically generated, do not edit manually -->\n' +
       '<!-- see lib/utils/config/definitions.js -->\n\n'
   )
 
 const addBetweenTags = (doc, startTag, endTag, body) => {
   const startSplit = doc.split(startTag)
+  console.log(startSplit)
+
   if (startSplit.length !== 2) {
     throw new Error('Did not find exactly one start tag')
   }
@@ -42,14 +44,28 @@ const addBetweenTags = (doc, startTag, endTag, body) => {
 const addDescriptions = doc => {
   const startTag = '<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->'
   const endTag = '<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->'
-  return addBetweenTags(doc, startTag, endTag, describeAll())
+  return addBetweenTags(doc, startTag, endTag, describeAll(params))
+}
+
+const addUsageDescriptions = doc => {
+  const startTag = '<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->'
+  const endTag = '<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->'
+  return addBetweenTags(doc, startTag, endTag, describeAll(usage))
 }
 
 // always write SOMETHING so that Make sees the file is up to date.
 const doc = readFileSync(configDoc, 'utf8')
 const hasTag = doc.includes('<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->')
-const newDoc = params && hasTag ? addDescriptions(doc) : doc
+const hasUsageTag = doc.includes('<!-- AUTOGENERATED SYNOPSIS DESCRIPTIONS START -->')
+
+let newDoc = params && hasTag ? addDescriptions(doc) : doc
+newDoc = usage && hasUsageTag ? addUsageDescriptions(newDoc) : newDoc
+
 if (params && !hasTag) {
   console.error('WARNING: did not find config description section', configDoc)
 }
+
+if (usage && !hasUsageTag) {
+  console.error('WARNING: did not find usage description section', configDoc)
+}
 writeFileSync(configDoc, newDoc)

From 25fc0eeff00a2bc06bd140cd9beb1ee426f7da43 Mon Sep 17 00:00:00 2001
From: Wassim Chegham <github@wassim.dev>
Date: Fri, 18 Feb 2022 14:00:32 +0100
Subject: [PATCH 2/7] feat: improve usage auto-generation

---
 scripts/config-doc-command.js | 55 ++++++++++++++++++++++++++++++-----
 1 file changed, 47 insertions(+), 8 deletions(-)

diff --git a/scripts/config-doc-command.js b/scripts/config-doc-command.js
index 9fa3f83d01490..486f71b2a4a5c 100644
--- a/scripts/config-doc-command.js
+++ b/scripts/config-doc-command.js
@@ -6,7 +6,12 @@ const configDoc = process.argv[2]
 const commandFile = process.argv[3]
 
 // Note: commands without params skip this whole process.
-const { params, usage } = require(resolve(commandFile))
+const {
+  params,
+  usage,
+  alias,
+  options,
+} = require(resolve(commandFile))
 
 const describeAll = (content) =>
   content.map(name => definitions[name].describe()).join(
@@ -14,9 +19,34 @@ const describeAll = (content) =>
       '<!-- see lib/utils/config/definitions.js -->\n\n'
   )
 
-const addBetweenTags = (doc, startTag, endTag, body) => {
+const describeUsage = ({ usage, alias, options }) => {
+  const synopsis = []
+  synopsis.push('\n```bash')
+
+  if (usage) {
+    synopsis.push(usage.join('\n'))
+  }
+
+  if (alias) {
+    synopsis.push('\nalias: ' + alias.join(', '))
+  }
+
+  if (options) {
+    synopsis.push('\ncommon options:')
+    synopsis.push(options.join('\n'))
+  }
+
+  synopsis.push('```')
+  return synopsis.join('\n')
+}
+
+const addBetweenTags = (
+  doc,
+  startTag,
+  endTag,
+  body,
+  sourceFilepath = 'lib/utils/config/definitions.js') => {
   const startSplit = doc.split(startTag)
-  console.log(startSplit)
 
   if (startSplit.length !== 2) {
     throw new Error('Did not find exactly one start tag')
@@ -31,10 +61,10 @@ const addBetweenTags = (doc, startTag, endTag, body) => {
     startSplit[0],
     startTag,
     '\n<!-- automatically generated, do not edit manually -->\n' +
-      '<!-- see lib/utils/config/definitions.js -->\n',
+      '<!-- see ' + sourceFilepath + ' -->\n',
     body,
     '\n\n<!-- automatically generated, do not edit manually -->\n' +
-      '<!-- see lib/utils/config/definitions.js -->',
+      '<!-- see ' + sourceFilepath + ' -->',
     '\n\n',
     endTag,
     endSplit[1],
@@ -44,19 +74,28 @@ const addBetweenTags = (doc, startTag, endTag, body) => {
 const addDescriptions = doc => {
   const startTag = '<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->'
   const endTag = '<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->'
+
+  console.log('adding config descriptions')
+  console.log({ params })
   return addBetweenTags(doc, startTag, endTag, describeAll(params))
 }
 
 const addUsageDescriptions = doc => {
   const startTag = '<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->'
   const endTag = '<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->'
-  return addBetweenTags(doc, startTag, endTag, describeAll(usage))
+
+  console.log('adding usage descriptions')
+  console.log({ usage })
+  return addBetweenTags(doc, startTag, endTag,
+    describeUsage({ usage, alias, options }),
+    commandFile
+  )
 }
 
 // always write SOMETHING so that Make sees the file is up to date.
 const doc = readFileSync(configDoc, 'utf8')
 const hasTag = doc.includes('<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->')
-const hasUsageTag = doc.includes('<!-- AUTOGENERATED SYNOPSIS DESCRIPTIONS START -->')
+const hasUsageTag = doc.includes('<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->')
 
 let newDoc = params && hasTag ? addDescriptions(doc) : doc
 newDoc = usage && hasUsageTag ? addUsageDescriptions(newDoc) : newDoc
@@ -65,7 +104,7 @@ if (params && !hasTag) {
   console.error('WARNING: did not find config description section', configDoc)
 }
 
-if (usage && !hasUsageTag) {
+if ((usage || alias || options) && !hasUsageTag) {
   console.error('WARNING: did not find usage description section', configDoc)
 }
 writeFileSync(configDoc, newDoc)

From ccb9d31975ca5500de42c7e2caaaec593e1fac56 Mon Sep 17 00:00:00 2001
From: Wassim Chegham <github@wassim.dev>
Date: Mon, 21 Feb 2022 14:54:15 +0100
Subject: [PATCH 3/7] chore: auto-generate npm usage for each command

Fixes #4189
---
 docs/content/commands/npm-access.md          | 12 ++-
 docs/content/commands/npm-adduser.md         |  7 +-
 docs/content/commands/npm-audit.md           | 14 ++-
 docs/content/commands/npm-bin.md             |  5 +-
 docs/content/commands/npm-bugs.md            | 13 ++-
 docs/content/commands/npm-cache.md           | 24 ++++--
 docs/content/commands/npm-ci.md              |  5 +-
 docs/content/commands/npm-completion.md      |  5 +-
 docs/content/commands/npm-config.md          | 11 ++-
 docs/content/commands/npm-dedupe.md          | 26 ++++--
 docs/content/commands/npm-deprecate.md       | 11 ++-
 docs/content/commands/npm-diff.md            | 13 ++-
 docs/content/commands/npm-dist-tag.md        | 11 ++-
 docs/content/commands/npm-docs.md            | 11 ++-
 docs/content/commands/npm-doctor.md          |  5 +-
 docs/content/commands/npm-edit.md            | 11 ++-
 docs/content/commands/npm-exec.md            | 21 ++---
 docs/content/commands/npm-explain.md         |  9 ++
 docs/content/commands/npm-explore.md         |  9 ++
 docs/content/commands/npm-find-dupes.md      |  7 +-
 docs/content/commands/npm-fund.md            | 12 ++-
 docs/content/commands/npm-help-search.md     |  9 ++
 docs/content/commands/npm-help.md            | 11 +++
 docs/content/commands/npm-hook.md            | 13 ++-
 docs/content/commands/npm-init.md            | 14 ++-
 docs/content/commands/npm-install-ci-test.md |  7 +-
 docs/content/commands/npm-install-test.md    | 37 +++++---
 docs/content/commands/npm-install.md         | 38 ++++++---
 docs/content/commands/npm-link.md            | 22 ++++-
 docs/content/commands/npm-logout.md          |  5 +-
 docs/content/commands/npm-ls.md              | 11 ++-
 docs/content/commands/npm-org.md             | 17 +++-
 docs/content/commands/npm-outdated.md        |  9 ++
 docs/content/commands/npm-owner.md           | 11 ++-
 docs/content/commands/npm-pack.md            | 11 ++-
 docs/content/commands/npm-ping.md            |  5 +-
 docs/content/commands/npm-pkg.md             | 15 +++-
 docs/content/commands/npm-prefix.md          |  9 ++
 docs/content/commands/npm-profile.md         | 16 +++-
 docs/content/commands/npm-prune.md           | 11 ++-
 docs/content/commands/npm-publish.md         | 14 ++-
 docs/content/commands/npm-rebuild.md         |  9 ++
 docs/content/commands/npm-repo.md            |  9 ++
 docs/content/commands/npm-restart.md         |  9 ++
 docs/content/commands/npm-root.md            |  5 +-
 docs/content/commands/npm-run-script.md      | 13 ++-
 docs/content/commands/npm-search.md          | 11 ++-
 docs/content/commands/npm-set-script.md      |  9 ++
 docs/content/commands/npm-shrinkwrap.md      |  5 +-
 docs/content/commands/npm-star.md            |  9 ++
 docs/content/commands/npm-stars.md           | 10 +++
 docs/content/commands/npm-start.md           |  9 ++
 docs/content/commands/npm-stop.md            |  9 ++
 docs/content/commands/npm-team.md            | 19 +++--
 docs/content/commands/npm-test.md            | 11 ++-
 docs/content/commands/npm-token.md           | 16 +++-
 docs/content/commands/npm-uninstall.md       | 22 +++--
 docs/content/commands/npm-unstar.md          |  9 ++
 docs/content/commands/npm-update.md          | 31 ++++++-
 docs/content/commands/npm-version.md         | 15 +++-
 docs/content/commands/npm-view.md            | 13 ++-
 docs/content/commands/npm-whoami.md          |  5 +-
 docs/content/commands/npm.md                 |  5 +-
 docs/content/commands/npx.md                 | 19 +----
 scripts/config-doc-command.js                | 89 ++++++++++----------
 65 files changed, 659 insertions(+), 229 deletions(-)

diff --git a/docs/content/commands/npm-access.md b/docs/content/commands/npm-access.md
index 1f661c911f47d..162e94f1fec02 100644
--- a/docs/content/commands/npm-access.md
+++ b/docs/content/commands/npm-access.md
@@ -6,21 +6,27 @@ description: Set access level on published packages
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/access.js -->
+
 ```bash
 npm access public [<package>]
 npm access restricted [<package>]
-
 npm access grant <read-only|read-write> <scope:team> [<package>]
 npm access revoke <scope:team> [<package>]
-
 npm access 2fa-required [<package>]
 npm access 2fa-not-required [<package>]
-
 npm access ls-packages [<user>|<scope>|<scope:team>]
 npm access ls-collaborators [<package> [<user>]]
 npm access edit [<package>]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/access.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 Used to set access controls on private packages.
diff --git a/docs/content/commands/npm-adduser.md b/docs/content/commands/npm-adduser.md
index 21a31ca940e52..0e3df32ef1ea5 100644
--- a/docs/content/commands/npm-adduser.md
+++ b/docs/content/commands/npm-adduser.md
@@ -6,11 +6,8 @@ description: Add a registry user account
 
 ### Synopsis
 
-```bash
-npm adduser [--registry=url] [--scope=@orgname] [--auth-type=legacy]
-
-aliases: login, add-user
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
 
diff --git a/docs/content/commands/npm-audit.md b/docs/content/commands/npm-audit.md
index 58c614d793db2..323d38f64c14f 100644
--- a/docs/content/commands/npm-audit.md
+++ b/docs/content/commands/npm-audit.md
@@ -6,13 +6,19 @@ description: Run a security audit
 
 ### Synopsis
 
-```bash
-npm audit [--json] [--production] [--audit-level=(low|moderate|high|critical)]
-npm audit fix [--force|--package-lock-only|--dry-run|--production|--only=(dev|prod)]
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/audit.js -->
 
-common options: [--production] [--only=(dev|prod)]
+```bash
+npm audit [fix]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/audit.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 The audit command submits a description of the dependencies configured in
diff --git a/docs/content/commands/npm-bin.md b/docs/content/commands/npm-bin.md
index 2d7c1d5b8149e..b41e0a412c4db 100644
--- a/docs/content/commands/npm-bin.md
+++ b/docs/content/commands/npm-bin.md
@@ -6,9 +6,8 @@ description: Display npm bin folder
 
 ### Synopsis
 
-```bash
-npm bin [-g|--global]
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
 
diff --git a/docs/content/commands/npm-bugs.md b/docs/content/commands/npm-bugs.md
index f92241a14b95c..aeddeb848e81b 100644
--- a/docs/content/commands/npm-bugs.md
+++ b/docs/content/commands/npm-bugs.md
@@ -6,12 +6,21 @@ description: Report bugs for a package in a web browser
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/bugs.js -->
+
 ```bash
-npm bugs [<pkgname> [<pkgname> ...]]
+npm bugs [<pkgname>]
 
-aliases: issues
+alias: issues
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/bugs.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command tries to guess at the likely location of a package's bug
diff --git a/docs/content/commands/npm-cache.md b/docs/content/commands/npm-cache.md
index 6497a3988c938..091e26e8a7182 100644
--- a/docs/content/commands/npm-cache.md
+++ b/docs/content/commands/npm-cache.md
@@ -6,18 +6,26 @@ description: Manipulates packages cache
 
 ### Synopsis
 
-```bash
-npm cache add <tarball file>...
-npm cache add <folder>...
-npm cache add <tarball url>...
-npm cache add <name>@<version>...
-
-npm cache clean
-aliases: npm cache clear, npm cache rm
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- 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 clean [<key>]
+npm cache ls [<name>@<version>]
 npm cache verify
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/cache.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-ci.md b/docs/content/commands/npm-ci.md
index 1ce50c66d5faf..3645b6247a068 100644
--- a/docs/content/commands/npm-ci.md
+++ b/docs/content/commands/npm-ci.md
@@ -6,9 +6,8 @@ description: Install a project with a clean slate
 
 ### Synopsis
 
-```bash
-npm ci
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Description
 
diff --git a/docs/content/commands/npm-completion.md b/docs/content/commands/npm-completion.md
index 9dbd960913f27..d4841a6a63b89 100644
--- a/docs/content/commands/npm-completion.md
+++ b/docs/content/commands/npm-completion.md
@@ -6,9 +6,8 @@ description: Tab Completion for npm
 
 ### Synopsis
 
-```bash
-source <(npm completion)
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
 
diff --git a/docs/content/commands/npm-config.md b/docs/content/commands/npm-config.md
index 2d77f045cbc47..a66a198ce42d1 100644
--- a/docs/content/commands/npm-config.md
+++ b/docs/content/commands/npm-config.md
@@ -6,18 +6,25 @@ description: Manage the npm configuration files
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/config.js -->
+
 ```bash
 npm config set <key>=<value> [<key>=<value> ...]
 npm config get [<key> [<key> ...]]
 npm config delete <key> [<key> ...]
 npm config list [--json]
 npm config edit
-npm set <key>=<value> [<key>=<value> ...]
-npm get [<key> [<key> ...]]
 
 alias: c
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/config.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-dedupe.md b/docs/content/commands/npm-dedupe.md
index 53d2e64272a67..5cd00f7f4d2e4 100644
--- a/docs/content/commands/npm-dedupe.md
+++ b/docs/content/commands/npm-dedupe.md
@@ -6,12 +6,8 @@ description: Reduce duplication in the package tree
 
 ### Synopsis
 
-```bash
-npm dedupe
-npm ddp
-
-aliases: ddp
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Description
 
@@ -145,6 +141,24 @@ When package package-locks are disabled, automatic pruning of extraneous
 modules will also be disabled. To remove extraneous modules with
 package-locks disabled use `npm prune`.
 
+This configuration does not affect `npm ci`.
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
+#### `save`
+
+* Default: `true` unless when using `npm update` or `npm dedupe` where it
+  defaults to `false`
+* Type: Boolean
+
+Save installed packages to a `package.json` file as dependencies.
+
+When used with the `npm rm` command, removes the dependency from
+`package.json`.
+
+Will also prevent writing to `package-lock.json` if set to `false`.
+
 <!-- 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 438a54ec6e4f3..4345120d3744b 100644
--- a/docs/content/commands/npm-deprecate.md
+++ b/docs/content/commands/npm-deprecate.md
@@ -6,10 +6,19 @@ description: Deprecate a version of a package
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/deprecate.js -->
+
 ```bash
-npm deprecate <pkg>[@<version range>] <message>
+npm deprecate <pkg>[@<version>] <message>
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/deprecate.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-diff.md b/docs/content/commands/npm-diff.md
index 8d05df779f3ca..c4c9eafdb3524 100644
--- a/docs/content/commands/npm-diff.md
+++ b/docs/content/commands/npm-diff.md
@@ -6,14 +6,19 @@ description: The registry diff command
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/diff.js -->
+
 ```bash
 npm diff [...<paths>]
-npm diff --diff=<pkg-name> [...<paths>]
-npm diff --diff=<version-a> [--diff=<version-b>] [...<paths>]
-npm diff --diff=<spec-a> [--diff=<spec-b>] [...<paths>]
-npm diff [--diff-ignore-all-space] [--diff-name-only] [...<paths>]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/diff.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 Similar to its `git diff` counterpart, this command will print diff patches
diff --git a/docs/content/commands/npm-dist-tag.md b/docs/content/commands/npm-dist-tag.md
index a4e0243aac87b..a0f306cd4970d 100644
--- a/docs/content/commands/npm-dist-tag.md
+++ b/docs/content/commands/npm-dist-tag.md
@@ -6,14 +6,23 @@ description: Modify package distribution tags
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- 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>]
 
-aliases: dist-tags
+alias: dist-tags
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/dist-tag.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 Add, remove, and enumerate distribution tags on a package:
diff --git a/docs/content/commands/npm-docs.md b/docs/content/commands/npm-docs.md
index 970d17aa829c6..8d5a278286a88 100644
--- a/docs/content/commands/npm-docs.md
+++ b/docs/content/commands/npm-docs.md
@@ -6,12 +6,21 @@ description: Open documentation for a package in a web browser
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/docs.js -->
+
 ```bash
 npm docs [<pkgname> [<pkgname> ...]]
 
-aliases: home
+alias: home
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/docs.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command tries to guess at the likely location of a package's
diff --git a/docs/content/commands/npm-doctor.md b/docs/content/commands/npm-doctor.md
index 0cce60c7b7b15..1b915ff997726 100644
--- a/docs/content/commands/npm-doctor.md
+++ b/docs/content/commands/npm-doctor.md
@@ -6,9 +6,8 @@ description: Check your npm environment
 
 ### Synopsis
 
-```bash
-npm doctor
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
 
diff --git a/docs/content/commands/npm-edit.md b/docs/content/commands/npm-edit.md
index 5ae7f2481ae45..39fc49592c571 100644
--- a/docs/content/commands/npm-edit.md
+++ b/docs/content/commands/npm-edit.md
@@ -6,10 +6,19 @@ description: Edit an installed package
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/edit.js -->
+
 ```bash
-npm edit <pkg>
+npm edit <pkg>[/<subpkg>...]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/edit.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-exec.md b/docs/content/commands/npm-exec.md
index d154f5780b9c9..3645e336b9da9 100644
--- a/docs/content/commands/npm-exec.md
+++ b/docs/content/commands/npm-exec.md
@@ -6,26 +6,23 @@ description: Run a command from a local or remote npm package
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/exec.js -->
+
 ```bash
 npm exec -- <pkg>[@<version>] [args...]
 npm exec --package=<pkg>[@<version>] -- <cmd> [args...]
 npm exec -c '<cmd> [args...]'
 npm exec --package=foo -c '<cmd> [args...]'
-npm exec [--ws] [-w <workspace-name] [args...]
 
-npx <pkg>[@<specifier>] [args...]
-npx -p <pkg>[@<specifier>] <cmd> [args...]
-npx -c '<cmd> [args...]'
-npx -p <pkg>[@<specifier>] -c '<cmd> [args...]'
-Run without --call or positional args to open interactive subshell
+alias: x
+```
 
-alias: npm x, npx
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/exec.js -->
 
-common options:
---package=<pkg> (may be specified multiple times)
--p is a shorthand for --package only when using npx executable
--c <cmd> --call=<cmd> (may not be mixed with positional arguments)
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Description
 
diff --git a/docs/content/commands/npm-explain.md b/docs/content/commands/npm-explain.md
index 5f05cac0f906b..765221056585d 100644
--- a/docs/content/commands/npm-explain.md
+++ b/docs/content/commands/npm-explain.md
@@ -6,12 +6,21 @@ description: Explain installed packages
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/explain.js -->
+
 ```bash
 npm explain <folder | specifier>
 
 alias: why
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/explain.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command will print the chain of dependencies causing a given package
diff --git a/docs/content/commands/npm-explore.md b/docs/content/commands/npm-explore.md
index 3979da9573db0..90753c7e09199 100644
--- a/docs/content/commands/npm-explore.md
+++ b/docs/content/commands/npm-explore.md
@@ -6,10 +6,19 @@ description: Browse an installed package
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/explore.js -->
+
 ```bash
 npm explore <pkg> [ -- <command>]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/explore.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-find-dupes.md b/docs/content/commands/npm-find-dupes.md
index f7dc84f9c5306..6f792302723bd 100644
--- a/docs/content/commands/npm-find-dupes.md
+++ b/docs/content/commands/npm-find-dupes.md
@@ -6,9 +6,8 @@ description: Find duplication in the package tree
 
 ### Synopsis
 
-```bash
-npm find-dupes
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Description
 
@@ -82,6 +81,8 @@ When package package-locks are disabled, automatic pruning of extraneous
 modules will also be disabled. To remove extraneous modules with
 package-locks disabled use `npm prune`.
 
+This configuration does not affect `npm ci`.
+
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
diff --git a/docs/content/commands/npm-fund.md b/docs/content/commands/npm-fund.md
index 606b0a188c554..5b96e91ab8ccb 100644
--- a/docs/content/commands/npm-fund.md
+++ b/docs/content/commands/npm-fund.md
@@ -6,11 +6,19 @@ description: Retrieve funding information
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/fund.js -->
+
 ```bash
-npm fund [<pkg>]
-npm fund [-w <workspace-name>]
+npm fund [[<@scope>/]<pkg>]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/fund.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command retrieves information on how to fund the dependencies of a
diff --git a/docs/content/commands/npm-help-search.md b/docs/content/commands/npm-help-search.md
index 78553a14ecb01..152f9f6bec16f 100644
--- a/docs/content/commands/npm-help-search.md
+++ b/docs/content/commands/npm-help-search.md
@@ -6,10 +6,19 @@ description: Search npm help documentation
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/help-search.js -->
+
 ```bash
 npm help-search <text>
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/help-search.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-help.md b/docs/content/commands/npm-help.md
index a8002eef17156..83c595db696b9 100644
--- a/docs/content/commands/npm-help.md
+++ b/docs/content/commands/npm-help.md
@@ -6,10 +6,21 @@ description: Get help on npm
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/help.js -->
+
 ```bash
 npm help <term> [<terms..>]
+
+alias: hlep
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/help.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-hook.md b/docs/content/commands/npm-hook.md
index c91bce3075e7b..4a9805d02f9d4 100644
--- a/docs/content/commands/npm-hook.md
+++ b/docs/content/commands/npm-hook.md
@@ -6,13 +6,22 @@ description: Manage registry hooks
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/hook.js -->
+
 ```bash
+npm hook add <pkg> <url> <secret> [--type=<type>]
 npm hook ls [pkg]
-npm hook add <entity> <url> <secret>
-npm hook update <id> <url> [secret]
 npm hook rm <id>
+npm hook update <id> <url> <secret>
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/hook.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-init.md b/docs/content/commands/npm-init.md
index 7a96ccc389627..a2439dee267f4 100644
--- a/docs/content/commands/npm-init.md
+++ b/docs/content/commands/npm-init.md
@@ -7,14 +7,20 @@ description: Create a package.json file
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/init.js -->
 
 ```bash
-npm init [--yes|-y|--scope]
-npm init <@scope> (same as `npm exec <@scope>/create`)
-npm init [<@scope>/]<name> (same as `npm exec [<@scope>/]create-<name>`)
-npm init [-w <dir>] [args...]
+npm init [--force|-f|--yes|-y|--scope]
+npm init <@scope> (same as `npx <@scope>/create`)
+npm init [<@scope>/]<name> (same as `npx [<@scope>/]create-<name>`)
+
+aliases: create, innit
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/init.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Description
diff --git a/docs/content/commands/npm-install-ci-test.md b/docs/content/commands/npm-install-ci-test.md
index 5c37ed8f56128..af15b1d134faa 100644
--- a/docs/content/commands/npm-install-ci-test.md
+++ b/docs/content/commands/npm-install-ci-test.md
@@ -6,11 +6,8 @@ description: Install a project with a clean slate and run tests
 
 ### Synopsis
 
-```bash
-npm install-ci-test
-
-alias: npm cit
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Description
 
diff --git a/docs/content/commands/npm-install-test.md b/docs/content/commands/npm-install-test.md
index c464e5bd0b8c6..ed39c6705a484 100644
--- a/docs/content/commands/npm-install-test.md
+++ b/docs/content/commands/npm-install-test.md
@@ -6,20 +6,30 @@ description: Install package(s) and run tests
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/install-test.js -->
+
 ```bash
-npm install-test (with no args, in package dir)
-npm install-test [<@scope>/]<name>
-npm install-test [<@scope>/]<name>@<tag>
-npm install-test [<@scope>/]<name>@<version>
-npm install-test [<@scope>/]<name>@<version range>
+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 <folder>
+npm install-test <git:// url>
+npm install-test <github username>/<github project>
 
-alias: npm it
-common options: [--save|--save-dev|--save-optional] [--save-exact] [--dry-run]
+alias: it
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/install-test.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command runs an `npm install` followed immediately by an `npm test`. It
@@ -32,13 +42,16 @@ takes exactly the same arguments as `npm install`.
 <!-- see lib/utils/config/definitions.js -->
 #### `save`
 
-* Default: true
+* Default: `true` unless when using `npm update` or `npm dedupe` where it
+  defaults to `false`
 * Type: Boolean
 
-Save installed packages to a package.json file as dependencies.
+Save installed packages to a `package.json` file as dependencies.
 
 When used with the `npm rm` command, removes the dependency from
-package.json.
+`package.json`.
+
+Will also prevent writing to `package-lock.json` if set to `false`.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
@@ -133,6 +146,8 @@ When package package-locks are disabled, automatic pruning of extraneous
 modules will also be disabled. To remove extraneous modules with
 package-locks disabled use `npm prune`.
 
+This configuration does not affect `npm ci`.
+
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
diff --git a/docs/content/commands/npm-install.md b/docs/content/commands/npm-install.md
index b4f8da8373d05..66193e733133b 100644
--- a/docs/content/commands/npm-install.md
+++ b/docs/content/commands/npm-install.md
@@ -6,23 +6,30 @@ description: Install a package
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/install.js -->
+
 ```bash
-npm install (with no args, in package dir)
-npm install [<@scope>/]<name>
-npm install [<@scope>/]<name>@<tag>
-npm install [<@scope>/]<name>@<version>
-npm install [<@scope>/]<name>@<version range>
+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 <git-host>:<git-user>/<repo-name>
-npm install <git repo url>
+npm install <folder>
 npm install <tarball file>
 npm install <tarball url>
-npm install <folder>
+npm install <git:// url>
+npm install <github username>/<github project>
 
-aliases: npm i, npm add
-common options: [-P|--save-prod|-D|--save-dev|-O|--save-optional|--save-peer] [-E|--save-exact] [-B|--save-bundle] [--no-save] [--dry-run]
+aliases: i, in, ins, inst, insta, instal, isnt, isnta, isntal, add
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/install.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command installs a package and any packages that it depends on. If the
@@ -425,13 +432,16 @@ These are some of the most common options related to installation.
 <!-- see lib/utils/config/definitions.js -->
 #### `save`
 
-* Default: true
+* Default: `true` unless when using `npm update` or `npm dedupe` where it
+  defaults to `false`
 * Type: Boolean
 
-Save installed packages to a package.json file as dependencies.
+Save installed packages to a `package.json` file as dependencies.
 
 When used with the `npm rm` command, removes the dependency from
-package.json.
+`package.json`.
+
+Will also prevent writing to `package-lock.json` if set to `false`.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
@@ -526,6 +536,8 @@ When package package-locks are disabled, automatic pruning of extraneous
 modules will also be disabled. To remove extraneous modules with
 package-locks disabled use `npm prune`.
 
+This configuration does not affect `npm ci`.
+
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
diff --git a/docs/content/commands/npm-link.md b/docs/content/commands/npm-link.md
index d4ef41ae96462..892b55496c9b6 100644
--- a/docs/content/commands/npm-link.md
+++ b/docs/content/commands/npm-link.md
@@ -6,13 +6,22 @@ description: Symlink a package folder
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/link.js -->
+
 ```bash
 npm link (in package dir)
 npm link [<@scope>/]<pkg>[@<version>]
 
-alias: npm ln
+alias: ln
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/link.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This is handy for installing your own stuff, so that you can work on it and
@@ -116,13 +125,16 @@ workspace(s).
 <!-- see lib/utils/config/definitions.js -->
 #### `save`
 
-* Default: true
+* Default: `true` unless when using `npm update` or `npm dedupe` where it
+  defaults to `false`
 * Type: Boolean
 
-Save installed packages to a package.json file as dependencies.
+Save installed packages to a `package.json` file as dependencies.
 
 When used with the `npm rm` command, removes the dependency from
-package.json.
+`package.json`.
+
+Will also prevent writing to `package-lock.json` if set to `false`.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
@@ -217,6 +229,8 @@ When package package-locks are disabled, automatic pruning of extraneous
 modules will also be disabled. To remove extraneous modules with
 package-locks disabled use `npm prune`.
 
+This configuration does not affect `npm ci`.
+
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
diff --git a/docs/content/commands/npm-logout.md b/docs/content/commands/npm-logout.md
index cb7c8496fb479..40c0e6744388d 100644
--- a/docs/content/commands/npm-logout.md
+++ b/docs/content/commands/npm-logout.md
@@ -6,9 +6,8 @@ description: Log out of the registry
 
 ### Synopsis
 
-```bash
-npm logout [--registry=<url>] [--scope=<@scope>]
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
 
diff --git a/docs/content/commands/npm-ls.md b/docs/content/commands/npm-ls.md
index 3b33f0a3605e0..0f06e131f414b 100644
--- a/docs/content/commands/npm-ls.md
+++ b/docs/content/commands/npm-ls.md
@@ -6,12 +6,21 @@ description: List installed packages
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/ls.js -->
+
 ```bash
 npm ls [[<@scope>/]<pkg> ...]
 
-aliases: list, la, ll
+alias: list
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/ls.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command will print to stdout all the versions of packages that are
diff --git a/docs/content/commands/npm-org.md b/docs/content/commands/npm-org.md
index 2f08f61152992..975581c860df6 100644
--- a/docs/content/commands/npm-org.md
+++ b/docs/content/commands/npm-org.md
@@ -6,12 +6,23 @@ description: Manage orgs
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/org.js -->
+
 ```bash
-npm org set <orgname> <username> [developer | admin | owner]
-npm org rm <orgname> <username>
-npm org ls <orgname> [<username>]
+npm org set orgname username [developer | admin | owner]
+npm org rm orgname username
+npm org ls orgname [<username>]
+
+alias: ogr
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/org.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Example
diff --git a/docs/content/commands/npm-outdated.md b/docs/content/commands/npm-outdated.md
index 1b58a6afda64b..6fa026550e747 100644
--- a/docs/content/commands/npm-outdated.md
+++ b/docs/content/commands/npm-outdated.md
@@ -6,10 +6,19 @@ description: Check for outdated packages
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/outdated.js -->
+
 ```bash
 npm outdated [[<@scope>/]<pkg> ...]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/outdated.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command will check the registry to see if any (or, specific) installed
diff --git a/docs/content/commands/npm-owner.md b/docs/content/commands/npm-owner.md
index 74e7f84af6c80..0779984e19a9d 100644
--- a/docs/content/commands/npm-owner.md
+++ b/docs/content/commands/npm-owner.md
@@ -6,14 +6,23 @@ description: Manage package owners
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/owner.js -->
+
 ```bash
 npm owner add <user> [<@scope>/]<pkg>
 npm owner rm <user> [<@scope>/]<pkg>
 npm owner ls [<@scope>/]<pkg>
 
-aliases: author
+alias: author
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/owner.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-pack.md b/docs/content/commands/npm-pack.md
index 53945986837b9..c834f643ac0bb 100644
--- a/docs/content/commands/npm-pack.md
+++ b/docs/content/commands/npm-pack.md
@@ -6,10 +6,19 @@ description: Create a tarball from a package
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/pack.js -->
+
 ```bash
-npm pack [[<@scope>/]<pkg>...] [--dry-run] [--json]
+npm pack [[<@scope>/]<pkg>...]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/pack.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Configuration
 
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
diff --git a/docs/content/commands/npm-ping.md b/docs/content/commands/npm-ping.md
index 6f1c4582f058f..f0469dd5c38c0 100644
--- a/docs/content/commands/npm-ping.md
+++ b/docs/content/commands/npm-ping.md
@@ -6,9 +6,8 @@ description: Ping npm registry
 
 ### Synopsis
 
-```bash
-npm ping [--registry <registry>]
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
 
diff --git a/docs/content/commands/npm-pkg.md b/docs/content/commands/npm-pkg.md
index beee9c1c4e78a..8f6cbecf958fd 100644
--- a/docs/content/commands/npm-pkg.md
+++ b/docs/content/commands/npm-pkg.md
@@ -6,12 +6,21 @@ description: Manages your package.json
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/pkg.js -->
+
 ```bash
-npm pkg get [<field> [.<subfield> ...]]
-npm pkg set <field>=<value> [.<subfield>=<value> ...]
-npm pkg delete <field> [.<subfield> ...]
+npm pkg set <key>=<value> [<key>=<value> ...]
+npm pkg get [<key> [<key> ...]]
+npm pkg delete <key> [<key> ...]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/pkg.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 A command that automates the management of `package.json` files.
diff --git a/docs/content/commands/npm-prefix.md b/docs/content/commands/npm-prefix.md
index 276a9e9e69910..39328bcc88a14 100644
--- a/docs/content/commands/npm-prefix.md
+++ b/docs/content/commands/npm-prefix.md
@@ -6,10 +6,19 @@ description: Display prefix
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/prefix.js -->
+
 ```bash
 npm prefix [-g]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/prefix.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-profile.md b/docs/content/commands/npm-profile.md
index cecc48518dbdb..af1f9d8aa1063 100644
--- a/docs/content/commands/npm-profile.md
+++ b/docs/content/commands/npm-profile.md
@@ -6,14 +6,22 @@ description: Change settings on your registry profile
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/profile.js -->
+
 ```bash
-npm profile get [--json|--parseable] [<property>]
-npm profile set [--json|--parseable] <property> <value>
-npm profile set password
-npm profile enable-2fa [auth-and-writes|auth-only]
+npm profile enable-2fa [auth-only|auth-and-writes]
 npm profile disable-2fa
+npm profile get [<key>]
+npm profile set <key> <value>
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/profile.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-prune.md b/docs/content/commands/npm-prune.md
index 658ab2610e0ed..49420e5b9d99c 100644
--- a/docs/content/commands/npm-prune.md
+++ b/docs/content/commands/npm-prune.md
@@ -6,10 +6,19 @@ description: Remove extraneous packages
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/prune.js -->
+
 ```bash
-npm prune [[<@scope>/]<pkg>...] [--production] [--dry-run] [--json]
+npm prune [[<@scope>/]<pkg>...]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/prune.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command removes "extraneous" packages.  If a package name is provided,
diff --git a/docs/content/commands/npm-publish.md b/docs/content/commands/npm-publish.md
index 6958b1066de7f..ce6e1c1012c8e 100644
--- a/docs/content/commands/npm-publish.md
+++ b/docs/content/commands/npm-publish.md
@@ -6,13 +6,19 @@ description: Publish a package
 
 ### Synopsis
 
-```bash
-npm publish [<tarball>|<folder>] [--tag <tag>] [--access <public|restricted>] [--otp otpcode] [--dry-run]
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/publish.js -->
 
-Publishes '.' if no argument supplied
-Sets tag 'latest' if no --tag specified
+```bash
+npm publish [<folder>]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/publish.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 Publishes a package to the registry so that it can be installed by name.
diff --git a/docs/content/commands/npm-rebuild.md b/docs/content/commands/npm-rebuild.md
index 75e71c60e6810..ecb4a7ce34c62 100644
--- a/docs/content/commands/npm-rebuild.md
+++ b/docs/content/commands/npm-rebuild.md
@@ -6,12 +6,21 @@ description: Rebuild a package
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/rebuild.js -->
+
 ```bash
 npm rebuild [[<@scope>/]<name>[@<version>] ...]
 
 alias: rb
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/rebuild.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command runs the `npm build` command on the matched folders.  This is
diff --git a/docs/content/commands/npm-repo.md b/docs/content/commands/npm-repo.md
index cd47fde47127e..e14f07012a248 100644
--- a/docs/content/commands/npm-repo.md
+++ b/docs/content/commands/npm-repo.md
@@ -6,10 +6,19 @@ description: Open package repository page in the browser
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/repo.js -->
+
 ```bash
 npm repo [<pkgname> [<pkgname> ...]]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/repo.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command tries to guess at the likely location of a package's
diff --git a/docs/content/commands/npm-restart.md b/docs/content/commands/npm-restart.md
index 80f8ab77ef018..f01cd014e7435 100644
--- a/docs/content/commands/npm-restart.md
+++ b/docs/content/commands/npm-restart.md
@@ -6,10 +6,19 @@ description: Restart a package
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/restart.js -->
+
 ```bash
 npm restart [-- <args>]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/restart.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This restarts a project.  It is equivalent to running `npm run-script
diff --git a/docs/content/commands/npm-root.md b/docs/content/commands/npm-root.md
index 98d1108d33f75..8bc9e57a0c5e5 100644
--- a/docs/content/commands/npm-root.md
+++ b/docs/content/commands/npm-root.md
@@ -6,9 +6,8 @@ description: Display npm root
 
 ### Synopsis
 
-```bash
-npm root [-g]
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Description
 
diff --git a/docs/content/commands/npm-run-script.md b/docs/content/commands/npm-run-script.md
index 6dd602d03e00a..79b7c9a25780e 100644
--- a/docs/content/commands/npm-run-script.md
+++ b/docs/content/commands/npm-run-script.md
@@ -6,14 +6,21 @@ description: Run arbitrary package scripts
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/run-script.js -->
+
 ```bash
-npm run-script <command> [--if-present] [--silent] [-- <args>]
-npm run-script <command> [--workspace=<workspace-name>]
-npm run-script <command> [--workspaces]
+npm run-script <command> [-- <args>]
 
 aliases: run, rum, urn
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/run-script.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This runs an arbitrary command from a package's `"scripts"` object.  If no
diff --git a/docs/content/commands/npm-search.md b/docs/content/commands/npm-search.md
index 252822e719844..db6a12bafabf1 100644
--- a/docs/content/commands/npm-search.md
+++ b/docs/content/commands/npm-search.md
@@ -6,12 +6,21 @@ description: Search for packages
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/search.js -->
+
 ```bash
-npm search [-l|--long] [--json] [--parseable] [--no-description] [search terms ...]
+npm search [search terms ...]
 
 aliases: s, se, find
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/search.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-set-script.md b/docs/content/commands/npm-set-script.md
index 869ceede045ae..2d8e87db85219 100644
--- a/docs/content/commands/npm-set-script.md
+++ b/docs/content/commands/npm-set-script.md
@@ -7,10 +7,19 @@ description: Set tasks in the scripts section of package.json
 ### Synopsis
 An npm command that lets you create a task in the `scripts` section of the `package.json`.
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/set-script.js -->
+
 ```bash
 npm set-script [<script>] [<command>]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/set-script.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 
 **Example:**
 
diff --git a/docs/content/commands/npm-shrinkwrap.md b/docs/content/commands/npm-shrinkwrap.md
index 6786229469d2c..2ac86eb4aab62 100644
--- a/docs/content/commands/npm-shrinkwrap.md
+++ b/docs/content/commands/npm-shrinkwrap.md
@@ -6,9 +6,8 @@ description: Lock down dependency versions for publication
 
 ### Synopsis
 
-```bash
-npm shrinkwrap
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
 
diff --git a/docs/content/commands/npm-star.md b/docs/content/commands/npm-star.md
index 21109c350961b..bbec7ac5f9263 100644
--- a/docs/content/commands/npm-star.md
+++ b/docs/content/commands/npm-star.md
@@ -6,10 +6,19 @@ description: Mark your favorite packages
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/star.js -->
+
 ```bash
 npm star [<pkg>...]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/star.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-stars.md b/docs/content/commands/npm-stars.md
index 101559ad99ba2..b9153831533af 100644
--- a/docs/content/commands/npm-stars.md
+++ b/docs/content/commands/npm-stars.md
@@ -5,10 +5,20 @@ description: View packages marked as favorites
 ---
 
 ### Synopsis
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/stars.js -->
+
 ```bash
 npm stars [<user>]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/stars.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-start.md b/docs/content/commands/npm-start.md
index 50a54cb5e5b0b..8dd874b3c7d29 100644
--- a/docs/content/commands/npm-start.md
+++ b/docs/content/commands/npm-start.md
@@ -6,10 +6,19 @@ description: Start a package
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/start.js -->
+
 ```bash
 npm start [-- <args>]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/start.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This runs a predefined command specified in the `"start"` property of
diff --git a/docs/content/commands/npm-stop.md b/docs/content/commands/npm-stop.md
index d4de4caf3a625..9a3a55cf3f20e 100644
--- a/docs/content/commands/npm-stop.md
+++ b/docs/content/commands/npm-stop.md
@@ -6,10 +6,19 @@ description: Stop a package
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/stop.js -->
+
 ```bash
 npm stop [-- <args>]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/stop.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This runs a predefined command specified in the "stop" property of a
diff --git a/docs/content/commands/npm-team.md b/docs/content/commands/npm-team.md
index 6050af1dff213..dc26fb53aaff1 100644
--- a/docs/content/commands/npm-team.md
+++ b/docs/content/commands/npm-team.md
@@ -6,16 +6,23 @@ description: Manage organization teams and team memberships
 
 ### Synopsis
 
-```bash
-npm team create <scope:team>
-npm team destroy <scope:team>
-
-npm team add <scope:team> <user>
-npm team rm <scope:team> <user>
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/team.js -->
 
+```bash
+npm team create <scope:team> [--otp <otpcode>]
+npm team destroy <scope:team> [--otp <otpcode>]
+npm team add <scope:team> <user> [--otp <otpcode>]
+npm team rm <scope:team> <user> [--otp <otpcode>]
 npm team ls <scope>|<scope:team>
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/team.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-test.md b/docs/content/commands/npm-test.md
index 2059f93dec489..8a343ab299b34 100644
--- a/docs/content/commands/npm-test.md
+++ b/docs/content/commands/npm-test.md
@@ -6,12 +6,21 @@ description: Test a package
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/test.js -->
+
 ```bash
 npm test [-- <args>]
 
-aliases: t, tst
+aliases: tst, t
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/test.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This runs a predefined command specified in the `"test"` property of
diff --git a/docs/content/commands/npm-token.md b/docs/content/commands/npm-token.md
index 16da1f73192d6..856ad68c9c94f 100644
--- a/docs/content/commands/npm-token.md
+++ b/docs/content/commands/npm-token.md
@@ -5,12 +5,22 @@ description: Manage your authentication tokens
 ---
 
 ### Synopsis
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/token.js -->
+
 ```bash
-  npm token list [--json|--parseable]
-  npm token create [--read-only] [--cidr=1.1.1.1/24,2.2.2.2/16]
-  npm token revoke <id|token>
+npm token list
+npm token revoke <id|token>
+npm token create [--read-only] [--cidr=list]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/token.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-uninstall.md b/docs/content/commands/npm-uninstall.md
index 824d0d8760e0b..8132bf6bc40b6 100644
--- a/docs/content/commands/npm-uninstall.md
+++ b/docs/content/commands/npm-uninstall.md
@@ -6,12 +6,21 @@ description: Remove a package
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/uninstall.js -->
+
 ```bash
-npm uninstall [<@scope>/]<pkg>[@<version>]... [-S|--save|--no-save]
+npm uninstall [<@scope>/]<pkg>...
 
-aliases: remove, rm, r, un, unlink
+aliases: un, unlink, remove, rm, r
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/uninstall.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This uninstalls a package, completely removing everything npm installed
@@ -61,13 +70,16 @@ npm uninstall lodash --no-save
 <!-- see lib/utils/config/definitions.js -->
 #### `save`
 
-* Default: true
+* Default: `true` unless when using `npm update` or `npm dedupe` where it
+  defaults to `false`
 * Type: Boolean
 
-Save installed packages to a package.json file as dependencies.
+Save installed packages to a `package.json` file as dependencies.
 
 When used with the `npm rm` command, removes the dependency from
-package.json.
+`package.json`.
+
+Will also prevent writing to `package-lock.json` if set to `false`.
 
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
diff --git a/docs/content/commands/npm-unstar.md b/docs/content/commands/npm-unstar.md
index d6e3620772358..76202190da8c3 100644
--- a/docs/content/commands/npm-unstar.md
+++ b/docs/content/commands/npm-unstar.md
@@ -6,10 +6,19 @@ description: Remove an item from your favorite packages
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/unstar.js -->
+
 ```bash
 npm unstar [<pkg>...]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/unstar.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
diff --git a/docs/content/commands/npm-update.md b/docs/content/commands/npm-update.md
index 1889d60569fe5..e1b48a8ed4320 100644
--- a/docs/content/commands/npm-update.md
+++ b/docs/content/commands/npm-update.md
@@ -6,12 +6,21 @@ description: Update packages
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/update.js -->
+
 ```bash
-npm update [-g] [<pkg>...]
+npm update [<pkg>...]
 
-aliases: up, upgrade
+aliases: up, upgrade, udpate
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/update.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command will update all the packages listed to the latest version
@@ -239,6 +248,24 @@ When package package-locks are disabled, automatic pruning of extraneous
 modules will also be disabled. To remove extraneous modules with
 package-locks disabled use `npm prune`.
 
+This configuration does not affect `npm ci`.
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
+#### `save`
+
+* Default: `true` unless when using `npm update` or `npm dedupe` where it
+  defaults to `false`
+* Type: Boolean
+
+Save installed packages to a `package.json` file as dependencies.
+
+When used with the `npm rm` command, removes the dependency from
+`package.json`.
+
+Will also prevent writing to `package-lock.json` if set to `false`.
+
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
diff --git a/docs/content/commands/npm-version.md b/docs/content/commands/npm-version.md
index 91ab0dee042ec..b53dd64aeae85 100644
--- a/docs/content/commands/npm-version.md
+++ b/docs/content/commands/npm-version.md
@@ -6,14 +6,21 @@ description: Bump a package version
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/version.js -->
+
 ```bash
-npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease [--preid=<prerelease-id>] | from-git]
+npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]
 
-'npm [-v | --version]' to print npm version
-'npm view <pkg> version' to view a package's published version
-'npm ls' to inspect current package/dependency versions
+alias: verison
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/version.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Configuration
 
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
diff --git a/docs/content/commands/npm-view.md b/docs/content/commands/npm-view.md
index 9a1793f13fa56..53ca408a01224 100644
--- a/docs/content/commands/npm-view.md
+++ b/docs/content/commands/npm-view.md
@@ -6,12 +6,21 @@ description: View registry info
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/view.js -->
+
 ```bash
-npm view [<@scope>/]<name>[@<version>] [<field>[.<subfield>]...]
+npm view [<@scope>/]<pkg>[@<version>] [<field>[.subfield]...]
 
-aliases: info, show, v
+aliases: v, info, show
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/view.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command shows data about a package and prints it to stdout.
diff --git a/docs/content/commands/npm-whoami.md b/docs/content/commands/npm-whoami.md
index 2cd7ffde3f485..67ca6bf5a2e72 100644
--- a/docs/content/commands/npm-whoami.md
+++ b/docs/content/commands/npm-whoami.md
@@ -6,9 +6,8 @@ description: Display npm username
 
 ### Synopsis
 
-```bash
-npm whoami [--registry <registry>]
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
 
diff --git a/docs/content/commands/npm.md b/docs/content/commands/npm.md
index de510870640d1..aaf295dfde230 100644
--- a/docs/content/commands/npm.md
+++ b/docs/content/commands/npm.md
@@ -6,9 +6,8 @@ description: javascript package manager
 
 ### Synopsis
 
-```bash
-npm <command> [args]
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Version
 
diff --git a/docs/content/commands/npx.md b/docs/content/commands/npx.md
index c1aae0b9ff0f8..510b04c3d9ee1 100644
--- a/docs/content/commands/npx.md
+++ b/docs/content/commands/npx.md
@@ -6,23 +6,8 @@ description: Run a command from a local or remote npm package
 
 ### Synopsis
 
-```bash
-npm exec -- <pkg>[@<version>] [args...]
-npm exec --package=<pkg>[@<version>] -- <cmd> [args...]
-npm exec -c '<cmd> [args...]'
-npm exec --package=foo -c '<cmd> [args...]'
-
-npx <pkg>[@<specifier>] [args...]
-npx -p <pkg>[@<specifier>] <cmd> [args...]
-npx -c '<cmd> [args...]'
-npx -p <pkg>[@<specifier>] -c '<cmd> [args...]'
-
-alias: npm x, npx
-
---package=<pkg> (may be specified multiple times)
--p is a shorthand for --package only when using npx executable
--c <cmd> --call=<cmd> (may not be mixed with positional arguments)
-```
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Description
 
diff --git a/scripts/config-doc-command.js b/scripts/config-doc-command.js
index 486f71b2a4a5c..b9a2ffed049a8 100644
--- a/scripts/config-doc-command.js
+++ b/scripts/config-doc-command.js
@@ -1,16 +1,26 @@
 const { definitions } = require('../lib/utils/config/index.js')
+const usageFn = require('../lib/utils/usage.js')
 const { writeFileSync, readFileSync } = require('fs')
 const { resolve } = require('path')
 
 const configDoc = process.argv[2]
 const commandFile = process.argv[3]
 
+const TAGS = {
+  CONFIG: {
+    START: '<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->',
+    END: '<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->',
+  },
+  USAGE: {
+    START: '<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->',
+    END: '<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->',
+  },
+}
+
 // Note: commands without params skip this whole process.
 const {
   params,
   usage,
-  alias,
-  options,
 } = require(resolve(commandFile))
 
 const describeAll = (content) =>
@@ -19,21 +29,22 @@ const describeAll = (content) =>
       '<!-- see lib/utils/config/definitions.js -->\n\n'
   )
 
-const describeUsage = ({ usage, alias, options }) => {
+const describeUsage = ({ usage }) => {
   const synopsis = []
+  const commandName = commandFile.split('/').pop().split('.')[0]
   synopsis.push('\n```bash')
 
-  if (usage) {
-    synopsis.push(usage.join('\n'))
-  }
-
-  if (alias) {
-    synopsis.push('\nalias: ' + alias.join(', '))
-  }
-
-  if (options) {
-    synopsis.push('\ncommon options:')
-    synopsis.push(options.join('\n'))
+  if (commandName) {
+    if (usage) {
+      synopsis.push(usage.map(usageInfo => `npm ${commandName} ${usageInfo}`).join('\n'))
+    }
+
+    const aliases = usageFn(commandName, '').trim()
+    if (aliases) {
+      synopsis.push(`\n${aliases}`)
+    }
+  } else {
+    console.error(`could not determine command name from ${commandFile}`)
   }
 
   synopsis.push('```')
@@ -71,40 +82,32 @@ const addBetweenTags = (
   ].join('')
 }
 
-const addDescriptions = doc => {
-  const startTag = '<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->'
-  const endTag = '<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->'
+const addDescriptions = doc =>
+  addBetweenTags(doc, TAGS.CONFIG.START, TAGS.CONFIG.END, describeAll(params))
 
-  console.log('adding config descriptions')
-  console.log({ params })
-  return addBetweenTags(doc, startTag, endTag, describeAll(params))
-}
-
-const addUsageDescriptions = doc => {
-  const startTag = '<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->'
-  const endTag = '<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->'
-
-  console.log('adding usage descriptions')
-  console.log({ usage })
-  return addBetweenTags(doc, startTag, endTag,
-    describeUsage({ usage, alias, options }),
+const addUsageDescriptions = doc =>
+  addBetweenTags(doc, TAGS.USAGE.START, TAGS.USAGE.END,
+    describeUsage({ usage }),
     commandFile
   )
-}
 
-// always write SOMETHING so that Make sees the file is up to date.
-const doc = readFileSync(configDoc, 'utf8')
-const hasTag = doc.includes('<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->')
-const hasUsageTag = doc.includes('<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->')
+try {
+  // always write SOMETHING so that Make sees the file is up to date.
+  const doc = readFileSync(configDoc, 'utf8')
+  const hasTag = doc.includes(TAGS.CONFIG.START)
+  const hasUsageTag = doc.includes(TAGS.USAGE.START)
 
-let newDoc = params && hasTag ? addDescriptions(doc) : doc
-newDoc = usage && hasUsageTag ? addUsageDescriptions(newDoc) : newDoc
+  let newDoc = params && hasTag ? addDescriptions(doc) : doc
+  newDoc = usage && hasUsageTag ? addUsageDescriptions(newDoc) : newDoc
 
-if (params && !hasTag) {
-  console.error('WARNING: did not find config description section', configDoc)
-}
+  if (params && !hasTag) {
+    console.error('WARNING: did not find config description section', configDoc)
+  }
 
-if ((usage || alias || options) && !hasUsageTag) {
-  console.error('WARNING: did not find usage description section', configDoc)
+  if (usage && !hasUsageTag) {
+    console.error('WARNING: did not find usage description section', configDoc)
+  }
+  writeFileSync(configDoc, newDoc)
+} catch (err) {
+  console.error(`WARNING: file cannot be open: ${configDoc}`)
 }
-writeFileSync(configDoc, newDoc)

From 2b43fb181144407d7ae48c6df267e752d8b4e56a Mon Sep 17 00:00:00 2001
From: Wassim Chegham <github@wassim.dev>
Date: Wed, 23 Feb 2022 17:15:53 +0100
Subject: [PATCH 4/7] docs: print default usage when usage is missing

Closes #4189
---
 docs/content/commands/npm-adduser.md         | 12 ++++++++++++
 docs/content/commands/npm-bin.md             | 10 ++++++++++
 docs/content/commands/npm-ci.md              | 12 ++++++++++++
 docs/content/commands/npm-completion.md      | 10 ++++++++++
 docs/content/commands/npm-dedupe.md          | 12 ++++++++++++
 docs/content/commands/npm-doctor.md          | 10 ++++++++++
 docs/content/commands/npm-find-dupes.md      | 10 ++++++++++
 docs/content/commands/npm-install-ci-test.md | 12 ++++++++++++
 docs/content/commands/npm-logout.md          | 10 ++++++++++
 docs/content/commands/npm-ping.md            | 10 ++++++++++
 docs/content/commands/npm-root.md            | 10 ++++++++++
 docs/content/commands/npm-shrinkwrap.md      | 10 ++++++++++
 docs/content/commands/npm-whoami.md          | 10 ++++++++++
 scripts/config-doc-command.js                |  6 ++++--
 14 files changed, 142 insertions(+), 2 deletions(-)

diff --git a/docs/content/commands/npm-adduser.md b/docs/content/commands/npm-adduser.md
index 0e3df32ef1ea5..06eeb379c4dd8 100644
--- a/docs/content/commands/npm-adduser.md
+++ b/docs/content/commands/npm-adduser.md
@@ -7,6 +7,18 @@ description: Add a registry user account
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/adduser.js -->
+
+```bash
+npm adduser
+
+aliases: login, add-user
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/adduser.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
diff --git a/docs/content/commands/npm-bin.md b/docs/content/commands/npm-bin.md
index b41e0a412c4db..94b72cfd5c81c 100644
--- a/docs/content/commands/npm-bin.md
+++ b/docs/content/commands/npm-bin.md
@@ -7,6 +7,16 @@ description: Display npm bin folder
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/bin.js -->
+
+```bash
+npm bin
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/bin.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
diff --git a/docs/content/commands/npm-ci.md b/docs/content/commands/npm-ci.md
index 3645b6247a068..4490fea9a0bb7 100644
--- a/docs/content/commands/npm-ci.md
+++ b/docs/content/commands/npm-ci.md
@@ -7,6 +7,18 @@ description: Install a project with a clean slate
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/ci.js -->
+
+```bash
+npm ci
+
+aliases: clean-install, ic, install-clean, isntall-clean
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/ci.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Description
diff --git a/docs/content/commands/npm-completion.md b/docs/content/commands/npm-completion.md
index d4841a6a63b89..d73a98f2e50f7 100644
--- a/docs/content/commands/npm-completion.md
+++ b/docs/content/commands/npm-completion.md
@@ -7,6 +7,16 @@ description: Tab Completion for npm
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/completion.js -->
+
+```bash
+npm completion
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/completion.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
diff --git a/docs/content/commands/npm-dedupe.md b/docs/content/commands/npm-dedupe.md
index 5cd00f7f4d2e4..b5a64831c0bba 100644
--- a/docs/content/commands/npm-dedupe.md
+++ b/docs/content/commands/npm-dedupe.md
@@ -7,6 +7,18 @@ description: Reduce duplication in the package tree
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/dedupe.js -->
+
+```bash
+npm dedupe
+
+alias: ddp
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/dedupe.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Description
diff --git a/docs/content/commands/npm-doctor.md b/docs/content/commands/npm-doctor.md
index 1b915ff997726..7fb63bab16e83 100644
--- a/docs/content/commands/npm-doctor.md
+++ b/docs/content/commands/npm-doctor.md
@@ -7,6 +7,16 @@ description: Check your npm environment
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/doctor.js -->
+
+```bash
+npm doctor
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/doctor.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
diff --git a/docs/content/commands/npm-find-dupes.md b/docs/content/commands/npm-find-dupes.md
index 6f792302723bd..f7366fa6375d1 100644
--- a/docs/content/commands/npm-find-dupes.md
+++ b/docs/content/commands/npm-find-dupes.md
@@ -7,6 +7,16 @@ description: Find duplication in the package tree
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/find-dupes.js -->
+
+```bash
+npm find-dupes
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/find-dupes.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Description
diff --git a/docs/content/commands/npm-install-ci-test.md b/docs/content/commands/npm-install-ci-test.md
index af15b1d134faa..5ad67604541d1 100644
--- a/docs/content/commands/npm-install-ci-test.md
+++ b/docs/content/commands/npm-install-ci-test.md
@@ -7,6 +7,18 @@ description: Install a project with a clean slate and run tests
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/install-ci-test.js -->
+
+```bash
+npm install-ci-test
+
+alias: cit
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/install-ci-test.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Description
diff --git a/docs/content/commands/npm-logout.md b/docs/content/commands/npm-logout.md
index 40c0e6744388d..f0dd5cb856eae 100644
--- a/docs/content/commands/npm-logout.md
+++ b/docs/content/commands/npm-logout.md
@@ -7,6 +7,16 @@ description: Log out of the registry
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/logout.js -->
+
+```bash
+npm logout
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/logout.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
diff --git a/docs/content/commands/npm-ping.md b/docs/content/commands/npm-ping.md
index f0469dd5c38c0..c950274598be5 100644
--- a/docs/content/commands/npm-ping.md
+++ b/docs/content/commands/npm-ping.md
@@ -7,6 +7,16 @@ description: Ping npm registry
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/ping.js -->
+
+```bash
+npm ping
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/ping.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
diff --git a/docs/content/commands/npm-root.md b/docs/content/commands/npm-root.md
index 8bc9e57a0c5e5..40b58e4b33d0b 100644
--- a/docs/content/commands/npm-root.md
+++ b/docs/content/commands/npm-root.md
@@ -7,6 +7,16 @@ description: Display npm root
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/root.js -->
+
+```bash
+npm root
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/root.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Description
diff --git a/docs/content/commands/npm-shrinkwrap.md b/docs/content/commands/npm-shrinkwrap.md
index 2ac86eb4aab62..043b4ad1b1bb4 100644
--- a/docs/content/commands/npm-shrinkwrap.md
+++ b/docs/content/commands/npm-shrinkwrap.md
@@ -7,6 +7,16 @@ description: Lock down dependency versions for publication
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/shrinkwrap.js -->
+
+```bash
+npm shrinkwrap
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/shrinkwrap.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
diff --git a/docs/content/commands/npm-whoami.md b/docs/content/commands/npm-whoami.md
index 67ca6bf5a2e72..18416f633a1d8 100644
--- a/docs/content/commands/npm-whoami.md
+++ b/docs/content/commands/npm-whoami.md
@@ -7,6 +7,16 @@ description: Display npm username
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/whoami.js -->
+
+```bash
+npm whoami
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/whoami.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 Note: This command is unaware of workspaces.
diff --git a/scripts/config-doc-command.js b/scripts/config-doc-command.js
index b9a2ffed049a8..8bb284f62762f 100644
--- a/scripts/config-doc-command.js
+++ b/scripts/config-doc-command.js
@@ -35,7 +35,9 @@ const describeUsage = ({ usage }) => {
   synopsis.push('\n```bash')
 
   if (commandName) {
-    if (usage) {
+    if (!usage) {
+      synopsis.push(`npm ${commandName}`)
+    } else {
       synopsis.push(usage.map(usageInfo => `npm ${commandName} ${usageInfo}`).join('\n'))
     }
 
@@ -98,7 +100,7 @@ try {
   const hasUsageTag = doc.includes(TAGS.USAGE.START)
 
   let newDoc = params && hasTag ? addDescriptions(doc) : doc
-  newDoc = usage && hasUsageTag ? addUsageDescriptions(newDoc) : newDoc
+  newDoc = hasUsageTag ? addUsageDescriptions(newDoc) : newDoc
 
   if (params && !hasTag) {
     console.error('WARNING: did not find config description section', configDoc)

From d238424770ecb9fc09249f621e85601f8dbac9d1 Mon Sep 17 00:00:00 2001
From: Wassim Chegham <github@wassim.dev>
Date: Wed, 23 Feb 2022 21:12:59 +0100
Subject: [PATCH 5/7] docs: add special case for npx

Closes #4189
---
 docs/content/commands/npm-exec.md |  8 ++++----
 scripts/config-doc-command.js     | 29 +++++++++++++++++++----------
 2 files changed, 23 insertions(+), 14 deletions(-)

diff --git a/docs/content/commands/npm-exec.md b/docs/content/commands/npm-exec.md
index 3645e336b9da9..674bb95524200 100644
--- a/docs/content/commands/npm-exec.md
+++ b/docs/content/commands/npm-exec.md
@@ -11,10 +11,10 @@ description: Run a command from a local or remote npm package
 <!-- see lib/commands/exec.js -->
 
 ```bash
-npm exec -- <pkg>[@<version>] [args...]
-npm exec --package=<pkg>[@<version>] -- <cmd> [args...]
-npm exec -c '<cmd> [args...]'
-npm exec --package=foo -c '<cmd> [args...]'
+npx -- <pkg>[@<version>] [args...]
+npx --package=<pkg>[@<version>] -- <cmd> [args...]
+npx -c '<cmd> [args...]'
+npx --package=foo -c '<cmd> [args...]'
 
 alias: x
 ```
diff --git a/scripts/config-doc-command.js b/scripts/config-doc-command.js
index 8bb284f62762f..c25361d89cad3 100644
--- a/scripts/config-doc-command.js
+++ b/scripts/config-doc-command.js
@@ -35,10 +35,17 @@ const describeUsage = ({ usage }) => {
   synopsis.push('\n```bash')
 
   if (commandName) {
+    let baseCommand = `npm ${commandName}`
+
+    // special case for `npx`
+    if (commandName === 'exec') {
+      baseCommand = 'npx'
+    }
+
     if (!usage) {
-      synopsis.push(`npm ${commandName}`)
+      synopsis.push(baseCommand)
     } else {
-      synopsis.push(usage.map(usageInfo => `npm ${commandName} ${usageInfo}`).join('\n'))
+      synopsis.push(usage.map(usageInfo => `${baseCommand} ${usageInfo}`).join('\n'))
     }
 
     const aliases = usageFn(commandName, '').trim()
@@ -99,17 +106,19 @@ try {
   const hasTag = doc.includes(TAGS.CONFIG.START)
   const hasUsageTag = doc.includes(TAGS.USAGE.START)
 
-  let newDoc = params && hasTag ? addDescriptions(doc) : doc
-  newDoc = hasUsageTag ? addUsageDescriptions(newDoc) : newDoc
+  if (params.length) {
+    let newDoc = hasTag ? addDescriptions(doc) : doc
+    newDoc = hasUsageTag ? addUsageDescriptions(newDoc) : newDoc
 
-  if (params && !hasTag) {
-    console.error('WARNING: did not find config description section', configDoc)
-  }
+    if (!hasTag) {
+      console.error('WARNING: did not find config description section', configDoc)
+    }
 
-  if (usage && !hasUsageTag) {
-    console.error('WARNING: did not find usage description section', configDoc)
+    if (usage.length && !hasUsageTag) {
+      console.error('WARNING: did not find usage description section', configDoc)
+    }
+    writeFileSync(configDoc, newDoc)
   }
-  writeFileSync(configDoc, newDoc)
 } catch (err) {
   console.error(`WARNING: file cannot be open: ${configDoc}`)
 }

From 36e0230f2ec7bd0beea3629a6c8a46d42a6bc8f7 Mon Sep 17 00:00:00 2001
From: Wassim Chegham <github@wassim.dev>
Date: Thu, 24 Feb 2022 10:38:45 +0100
Subject: [PATCH 6/7] docs: special case for npx

Closes #4189
---
 docs/content/commands/npm-exec.md |  8 +++---
 docs/content/commands/npx.md      | 13 ++++++++++
 scripts/config-doc-command.js     | 42 ++++++++++++++++++-------------
 3 files changed, 41 insertions(+), 22 deletions(-)

diff --git a/docs/content/commands/npm-exec.md b/docs/content/commands/npm-exec.md
index 674bb95524200..3645e336b9da9 100644
--- a/docs/content/commands/npm-exec.md
+++ b/docs/content/commands/npm-exec.md
@@ -11,10 +11,10 @@ description: Run a command from a local or remote npm package
 <!-- see lib/commands/exec.js -->
 
 ```bash
-npx -- <pkg>[@<version>] [args...]
-npx --package=<pkg>[@<version>] -- <cmd> [args...]
-npx -c '<cmd> [args...]'
-npx --package=foo -c '<cmd> [args...]'
+npm exec -- <pkg>[@<version>] [args...]
+npm exec --package=<pkg>[@<version>] -- <cmd> [args...]
+npm exec -c '<cmd> [args...]'
+npm exec --package=foo -c '<cmd> [args...]'
 
 alias: x
 ```
diff --git a/docs/content/commands/npx.md b/docs/content/commands/npx.md
index 510b04c3d9ee1..e7e59d00d84c1 100644
--- a/docs/content/commands/npx.md
+++ b/docs/content/commands/npx.md
@@ -7,6 +7,19 @@ description: Run a command from a local or remote npm package
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/exec.js -->
+
+```bash
+npx -- <pkg>[@<version>] [args...]
+npx --package=<pkg>[@<version>] -- <cmd> [args...]
+npx -c '<cmd> [args...]'
+npx --package=foo -c '<cmd> [args...]'
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/exec.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Description
diff --git a/scripts/config-doc-command.js b/scripts/config-doc-command.js
index c25361d89cad3..5b1e7689ea6dd 100644
--- a/scripts/config-doc-command.js
+++ b/scripts/config-doc-command.js
@@ -31,26 +31,31 @@ const describeAll = (content) =>
 
 const describeUsage = ({ usage }) => {
   const synopsis = []
-  const commandName = commandFile.split('/').pop().split('.')[0]
+
+  // Grab the command name from the *.md filename
+  // NOTE: We cannot use the name property command file because in the case of
+  // `npx` the file being used is `lib/commands/exec.js`
+  const commandName = configDoc.split('/').pop().split('.')[0].replace('npm-', '')
   synopsis.push('\n```bash')
 
   if (commandName) {
-    let baseCommand = `npm ${commandName}`
-
-    // special case for `npx`
-    if (commandName === 'exec') {
-      baseCommand = 'npx'
-    }
-
-    if (!usage) {
-      synopsis.push(baseCommand)
+    // special case for `npx`:
+    // `npx` is not technically a command in and of itself,
+    // so it just needs the usage and parameters of npm exec, and none of the aliases
+    if (commandName === 'npx') {
+      synopsis.push(usage.map(usageInfo => `npx ${usageInfo}`).join('\n'))
     } else {
-      synopsis.push(usage.map(usageInfo => `${baseCommand} ${usageInfo}`).join('\n'))
-    }
-
-    const aliases = usageFn(commandName, '').trim()
-    if (aliases) {
-      synopsis.push(`\n${aliases}`)
+      const baseCommand = `npm ${commandName}`
+      if (!usage) {
+        synopsis.push(baseCommand)
+      } else {
+        synopsis.push(usage.map(usageInfo => `${baseCommand} ${usageInfo}`).join('\n'))
+      }
+
+      const aliases = usageFn(commandName, '').trim()
+      if (aliases) {
+        synopsis.push(`\n${aliases}`)
+      }
     }
   } else {
     console.error(`could not determine command name from ${commandFile}`)
@@ -106,7 +111,7 @@ try {
   const hasTag = doc.includes(TAGS.CONFIG.START)
   const hasUsageTag = doc.includes(TAGS.USAGE.START)
 
-  if (params.length) {
+  if (params?.length) {
     let newDoc = hasTag ? addDescriptions(doc) : doc
     newDoc = hasUsageTag ? addUsageDescriptions(newDoc) : newDoc
 
@@ -114,11 +119,12 @@ try {
       console.error('WARNING: did not find config description section', configDoc)
     }
 
-    if (usage.length && !hasUsageTag) {
+    if (usage?.length && !hasUsageTag) {
       console.error('WARNING: did not find usage description section', configDoc)
     }
     writeFileSync(configDoc, newDoc)
   }
 } catch (err) {
   console.error(`WARNING: file cannot be open: ${configDoc}`)
+  console.error(err)
 }

From 0a4f8e42e557cf71ca87b99f8aa65a85c0450aa3 Mon Sep 17 00:00:00 2001
From: Wassim Chegham <github@wassim.dev>
Date: Thu, 24 Feb 2022 17:03:44 +0100
Subject: [PATCH 7/7] fix: remove optional chaining

---
 scripts/config-doc-command.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/config-doc-command.js b/scripts/config-doc-command.js
index 5b1e7689ea6dd..af008b7e1991c 100644
--- a/scripts/config-doc-command.js
+++ b/scripts/config-doc-command.js
@@ -111,7 +111,7 @@ try {
   const hasTag = doc.includes(TAGS.CONFIG.START)
   const hasUsageTag = doc.includes(TAGS.USAGE.START)
 
-  if (params?.length) {
+  if (params && params.length) {
     let newDoc = hasTag ? addDescriptions(doc) : doc
     newDoc = hasUsageTag ? addUsageDescriptions(newDoc) : newDoc
 
@@ -119,7 +119,7 @@ try {
       console.error('WARNING: did not find config description section', configDoc)
     }
 
-    if (usage?.length && !hasUsageTag) {
+    if ((usage && usage.length) && !hasUsageTag) {
       console.error('WARNING: did not find usage description section', configDoc)
     }
     writeFileSync(configDoc, newDoc)