From 6b68c1aaa282205eb4d47dbc81909c11851f7e06 Mon Sep 17 00:00:00 2001
From: Wassim Chegham <1699357+manekinekko@users.noreply.github.com>
Date: Thu, 24 Feb 2022 18:46:37 +0100
Subject: [PATCH] docs: auto-generate npm usage for each command  (#4450)

Closes #4189

* docs: auto-generate synopsis sections
* feat: improve usage auto-generation'
* chore: auto-generate npm usage for each command
* docs: print default usage when usage is missing
* docs: add special case for npx
* fix: remove optional chaining
---
 docs/content/commands/npm-access.md          |  12 +-
 docs/content/commands/npm-adduser.md         |  11 +-
 docs/content/commands/npm-audit.md           |  14 ++-
 docs/content/commands/npm-bin.md             |  11 +-
 docs/content/commands/npm-bugs.md            |  13 ++-
 docs/content/commands/npm-cache.md           |  24 ++--
 docs/content/commands/npm-ci.md              |  11 ++
 docs/content/commands/npm-completion.md      |  11 +-
 docs/content/commands/npm-config.md          |  11 +-
 docs/content/commands/npm-dedupe.md          |  30 ++++-
 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          |   9 ++
 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      |  11 ++
 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            |  18 ++-
 docs/content/commands/npm-install-ci-test.md |  11 +-
 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          |  11 +-
 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            |  11 +-
 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            |  11 +-
 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      |   9 ++
 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          |  11 +-
 docs/content/commands/npm.md                 |   5 +-
 docs/content/commands/npx.md                 |  24 ++--
 scripts/config-doc-command.js                | 111 ++++++++++++++++---
 65 files changed, 821 insertions(+), 164 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..06eeb379c4dd8 100644
--- a/docs/content/commands/npm-adduser.md
+++ b/docs/content/commands/npm-adduser.md
@@ -6,12 +6,21 @@ 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 [--registry=url] [--scope=@orgname] [--auth-type=legacy]
+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.
 
 ### Description
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..94b72cfd5c81c 100644
--- a/docs/content/commands/npm-bin.md
+++ b/docs/content/commands/npm-bin.md
@@ -6,10 +6,19 @@ description: Display npm bin folder
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/bin.js -->
+
 ```bash
-npm bin [-g|--global]
+npm bin
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/bin.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
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..4490fea9a0bb7 100644
--- a/docs/content/commands/npm-ci.md
+++ b/docs/content/commands/npm-ci.md
@@ -6,10 +6,21 @@ 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
 
 This command is similar to [`npm install`](/commands/npm-install), except
diff --git a/docs/content/commands/npm-completion.md b/docs/content/commands/npm-completion.md
index 9dbd960913f27..d73a98f2e50f7 100644
--- a/docs/content/commands/npm-completion.md
+++ b/docs/content/commands/npm-completion.md
@@ -6,10 +6,19 @@ description: Tab Completion for npm
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/completion.js -->
+
 ```bash
-source <(npm completion)
+npm completion
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/completion.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
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..b5a64831c0bba 100644
--- a/docs/content/commands/npm-dedupe.md
+++ b/docs/content/commands/npm-dedupe.md
@@ -6,13 +6,21 @@ 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
-npm ddp
 
-aliases: ddp
+alias: ddp
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/dedupe.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 Searches the local package tree and attempts to simplify the overall
@@ -145,6 +153,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..7fb63bab16e83 100644
--- a/docs/content/commands/npm-doctor.md
+++ b/docs/content/commands/npm-doctor.md
@@ -6,10 +6,19 @@ 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.
 
 ### Description
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..f7366fa6375d1 100644
--- a/docs/content/commands/npm-find-dupes.md
+++ b/docs/content/commands/npm-find-dupes.md
@@ -6,10 +6,19 @@ 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
 
 Runs `npm dedupe` in `--dry-run` mode, making npm only output the
@@ -82,6 +91,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 e9212a37e0f25..d9c03aef41504 100644
--- a/docs/content/commands/npm-init.md
+++ b/docs/content/commands/npm-init.md
@@ -6,13 +6,23 @@ 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
 
 `npm init <initializer>` can be used to set up a new or existing npm
diff --git a/docs/content/commands/npm-install-ci-test.md b/docs/content/commands/npm-install-ci-test.md
index 5c37ed8f56128..5ad67604541d1 100644
--- a/docs/content/commands/npm-install-ci-test.md
+++ b/docs/content/commands/npm-install-ci-test.md
@@ -6,12 +6,21 @@ 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: npm cit
+alias: cit
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/install-ci-test.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command runs `npm ci` followed immediately by `npm test`.
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..f0dd5cb856eae 100644
--- a/docs/content/commands/npm-logout.md
+++ b/docs/content/commands/npm-logout.md
@@ -6,10 +6,19 @@ 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 [--registry=<url>] [--scope=<@scope>]
+npm logout
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/logout.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
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 c59a56e611e54..161d7292f8c97 100644
--- a/docs/content/commands/npm-ping.md
+++ b/docs/content/commands/npm-ping.md
@@ -6,10 +6,19 @@ description: Ping npm registry
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/ping.js -->
+
 ```bash
-npm ping [--registry <registry>]
+npm ping
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/ping.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
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..40b58e4b33d0b 100644
--- a/docs/content/commands/npm-root.md
+++ b/docs/content/commands/npm-root.md
@@ -6,10 +6,19 @@ description: Display npm root
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/root.js -->
+
 ```bash
-npm root [-g]
+npm root
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/root.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 Print the effective `node_modules` folder to standard out.
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..043b4ad1b1bb4 100644
--- a/docs/content/commands/npm-shrinkwrap.md
+++ b/docs/content/commands/npm-shrinkwrap.md
@@ -6,10 +6,19 @@ 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.
 
 ### Description
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..18416f633a1d8 100644
--- a/docs/content/commands/npm-whoami.md
+++ b/docs/content/commands/npm-whoami.md
@@ -6,10 +6,19 @@ description: Display npm username
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/whoami.js -->
+
 ```bash
-npm whoami [--registry <registry>]
+npm whoami
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/whoami.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description
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..e7e59d00d84c1 100644
--- a/docs/content/commands/npx.md
+++ b/docs/content/commands/npx.md
@@ -6,23 +6,21 @@ 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...]'
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/exec.js -->
 
-npx <pkg>[@<specifier>] [args...]
-npx -p <pkg>[@<specifier>] <cmd> [args...]
+```bash
+npx -- <pkg>[@<version>] [args...]
+npx --package=<pkg>[@<version>] -- <cmd> [args...]
 npx -c '<cmd> [args...]'
-npx -p <pkg>[@<specifier>] -c '<cmd> [args...]'
+npx --package=foo -c '<cmd> [args...]'
+```
 
-alias: npm x, npx
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/exec.js -->
 
---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/scripts/config-doc-command.js b/scripts/config-doc-command.js
index 9db026f304281..af008b7e1991c 100644
--- a/scripts/config-doc-command.js
+++ b/scripts/config-doc-command.js
@@ -1,21 +1,78 @@
 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 } = 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 describeUsage = ({ usage }) => {
+  const synopsis = []
+
+  // 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) {
+    // 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 {
+      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}`)
+  }
+
+  synopsis.push('```')
+  return synopsis.join('\n')
+}
+
+const addBetweenTags = (
+  doc,
+  startTag,
+  endTag,
+  body,
+  sourceFilepath = 'lib/utils/config/definitions.js') => {
   const startSplit = doc.split(startTag)
+
   if (startSplit.length !== 2) {
     throw new Error('Did not find exactly one start tag')
   }
@@ -29,27 +86,45 @@ 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],
   ].join('')
 }
 
-const addDescriptions = doc => {
-  const startTag = '<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->'
-  const endTag = '<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->'
-  return addBetweenTags(doc, startTag, endTag, describeAll())
-}
+const addDescriptions = doc =>
+  addBetweenTags(doc, TAGS.CONFIG.START, TAGS.CONFIG.END, describeAll(params))
+
+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 newDoc = params && hasTag ? addDescriptions(doc) : doc
-if (params && !hasTag) {
-  console.error('WARNING: did not find config description section', configDoc)
+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)
+
+  if (params && params.length) {
+    let newDoc = hasTag ? addDescriptions(doc) : doc
+    newDoc = hasUsageTag ? addUsageDescriptions(newDoc) : newDoc
+
+    if (!hasTag) {
+      console.error('WARNING: did not find config description section', configDoc)
+    }
+
+    if ((usage && 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)
 }
-writeFileSync(configDoc, newDoc)