diff --git a/Makefile b/Makefile
index 4c96615203b02..656f64f79efd5 100644
--- a/Makefile
+++ b/Makefile
@@ -47,7 +47,7 @@ docs-clean:
 
 ## build-time dependencies for the documentation
 dev-deps:
-	node bin/npm-cli.js install --only=dev --no-audit --ignore-scripts
+	node bin/npm-cli.js install --no-audit --ignore-scripts
 
 ## targets for man files, these are encouraged to be only built by running `make docs` or `make mandocs`
 man/man1/%.1: docs/content/commands/%.md scripts/docs-build.js
@@ -68,6 +68,11 @@ man/man7/%.7: docs/content/using-npm/%.md scripts/docs-build.js
 	@[ -d man/man7 ] || mkdir -p man/man7
 	node scripts/docs-build.js $< $@
 
+# Any time the config definitions description changes, automatically
+# update the documentation to account for it
+docs/content/using-npm/config.md: scripts/config-doc.js lib/utils/config/*.js
+	node scripts/config-doc.js
+
 test: dev-deps
 	node bin/npm-cli.js test
 
diff --git a/docs/content/using-npm/config.md b/docs/content/using-npm/config.md
index 1032adafbeb22..435f9cee237da 100644
--- a/docs/content/using-npm/config.md
+++ b/docs/content/using-npm/config.md
@@ -59,30 +59,46 @@ internal to npm, and are defaults if nothing else is specified.
 
 The following shorthands are parsed on the command-line:
 
-* `-v`: `--version`
-* `-h`, `-?`, `--help`, `-H`: `--usage`
-* `-s`, `--silent`: `--loglevel silent`
-* `-q`, `--quiet`: `--loglevel warn`
-* `-d`: `--loglevel info`
-* `-dd`, `--verbose`: `--loglevel verbose`
-* `-ddd`: `--loglevel silly`
+<!-- AUTOGENERATED CONFIG SHORTHANDS START -->
+<!-- automatically generated, do not edit manually -->
+* `-a`: `--all`
+* `--enjoy-by`: `--before`
+* `-c`: `--call`
+* `--desc`: `--description`
+* `-f`: `--force`
 * `-g`: `--global`
-* `-C`: `--prefix`
+* `-d`: `--loglevel info`
+* `-s`: `--loglevel silent`
+* `--silent`: `--loglevel silent`
+* `--ddd`: `--loglevel silly`
+* `--dd`: `--loglevel verbose`
+* `--verbose`: `--loglevel verbose`
+* `-q`: `--loglevel warn`
+* `--quiet`: `--loglevel warn`
 * `-l`: `--long`
 * `-m`: `--message`
-* `-p`, `--porcelain`: `--parseable`
-* `-reg`: `--registry`
-* `-f`: `--force`
-* `-desc`: `--description`
+* `--local`: `--no-global`
+* `-n`: `--no-yes`
+* `--no`: `--no-yes`
+* `-p`: `--parseable`
+* `--porcelain`: `--parseable`
+* `-C`: `--prefix`
+* `--readonly`: `--read-only`
+* `--reg`: `--registry`
 * `-S`: `--save`
-* `-P`: `--save-prod`
-* `-D`: `--save-dev`
-* `-O`: `--save-optional`
 * `-B`: `--save-bundle`
+* `-D`: `--save-dev`
 * `-E`: `--save-exact`
+* `-O`: `--save-optional`
+* `-P`: `--save-prod`
+* `-?`: `--usage`
+* `-h`: `--usage`
+* `-H`: `--usage`
+* `--help`: `--usage`
+* `-v`: `--version`
 * `-y`: `--yes`
-* `-n`: `--yes false`
-* `ll` and `la` commands: `ls --long`
+
+<!-- AUTOGENERATED CONFIG SHORTHANDS END -->
 
 If the specified configuration param resolves unambiguously to a known
 configuration parameter, then it is expanded to that configuration
@@ -107,26 +123,39 @@ npm ls --global --parseable --long --loglevel info
 
 ### Config Settings
 
-#### access
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+#### `_auth`
+
+* Default: null
+* Type: null or String
+
+A basic-auth string to use when authenticating against the npm registry.
+
+Warning: This should generally not be set via a command-line option. It is
+safer to use a registry-provided authentication bearer token stored in the
+~/.npmrc file by running `npm login`.
 
-* Default: `restricted`
-* Type: Access
+#### `access`
 
-When publishing scoped packages, the access level defaults to `restricted`.  If
-you want your scoped package to be publicly viewable (and installable) set
-`--access=public`. The only valid values for `access` are `public` and
+* Default: 'restricted' for scoped packages, 'public' for unscoped packages
+* Type: null, "restricted", or "public"
+
+When publishing scoped packages, the access level defaults to `restricted`.
+If you want your scoped package to be publicly viewable (and installable)
+set `--access=public`. The only valid values for `access` are `public` and
 `restricted`. Unscoped packages _always_ have an access level of `public`.
 
-#### all
+#### `all`
 
-* Default: `false`
+* Default: false
 * Type: Boolean
 
 When running `npm outdated` and `npm ls`, setting `--all` will show all
 outdated or installed packages, rather than only those directly depended
 upon by the current project.
 
-#### allow-same-version
+#### `allow-same-version`
 
 * Default: false
 * Type: Boolean
@@ -134,78 +163,62 @@ upon by the current project.
 Prevents throwing an error when `npm version` is used to set the new version
 to the same value as the current version.
 
-#### always-auth
+#### `always-auth`
 
 * Default: false
 * Type: Boolean
 
-Force npm to always require authentication when accessing the registry,
-even for `GET` requests.
-
-#### also
-
-* Default: null
-* Type: String
+Force npm to always require authentication when accessing the registry, even
+for `GET` requests.
 
-When "dev" or "development" and running local `npm shrinkwrap`,
-`npm outdated`, or `npm update`, is an alias for `--dev`.
-
-#### audit
+#### `audit`
 
 * Default: true
 * Type: Boolean
 
 When "true" submit audit reports alongside `npm install` runs to the default
-registry and all registries configured for scopes.  See the documentation
-for [`npm audit`](/commands/npm-audit) for details on what is submitted.
-
-#### audit-level
-
-* Default: `"low"`
-* Type: `'low'`, `'moderate'`, `'high'`, `'critical'`
+registry and all registries configured for scopes. See the documentation for
+[`npm audit`](/commands/npm-audit) for details on what is submitted.
 
-The minimum level of vulnerability for `npm audit` to exit with
-a non-zero exit code.
+#### `audit-level`
 
-#### auth-type
-
-* Default: `'legacy'`
-* Type: `'legacy'`, `'sso'`, `'saml'`, `'oauth'`
+* Default: null
+* Type: "low", "moderate", "high", "critical", "none", or null
 
-What authentication strategy to use with `adduser`/`login`.
+The minimum level of vulnerability for `npm audit` to exit with a non-zero
+exit code.
 
-#### before
+#### `before`
 
-* Alias: enjoy-by
 * Default: null
-* Type: Date
+* Type: null or Date
 
-If passed to `npm install`, will rebuild the npm tree such that only versions
-that were available **on or before** the `--before` time get installed.
-If there's no versions available for the current set of direct dependencies, the
-command will error.
+If passed to `npm install`, will rebuild the npm tree such that only
+versions that were available **on or before** the `--before` time get
+installed. If there's no versions available for the current set of direct
+dependencies, the command will error.
 
 If the requested version is a `dist-tag` and the given tag does not pass the
-`--before` filter, the most recent version less than or equal to that tag will
-be used. For example, `foo@latest` might install `foo@1.2` even though `latest`
-is `2.0`.
+`--before` filter, the most recent version less than or equal to that tag
+will be used. For example, `foo@latest` might install `foo@1.2` even though
+`latest` is `2.0`.
 
-#### bin-links
+#### `bin-links`
 
-* Default: `true`
+* Default: true
 * Type: Boolean
 
 Tells npm to create symlinks (or `.cmd` shims on Windows) for package
 executables.
 
-Set to false to have it not do this.  This can be used to work around
-the fact that some file systems don't support symlinks, even on
-ostensibly Unix systems.
+Set to false to have it not do this. This can be used to work around the
+fact that some file systems don't support symlinks, even on ostensibly Unix
+systems.
 
-#### browser
+#### `browser`
 
 * Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"`
-* Type: String or Boolean
+* Type: null, Boolean, or String
 
 The browser that is called by npm commands to open websites.
 
@@ -214,87 +227,50 @@ terminal.
 
 Set to `true` to use default system URL opener.
 
-#### ca
+#### `ca`
 
-* Default: The npm CA certificate
-* Type: String, Array or null
+* Default: null
+* Type: null or String (can be set multiple times)
 
 The Certificate Authority signing certificate that is trusted for SSL
-connections to the registry. Values should be in PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with newlines
-replaced by the string "\n". For example:
+connections to the registry. Values should be in PEM format (Windows calls
+it "Base-64 encoded X.509 (.CER)") with newlines replaced by the string
+"\n". For example:
 
-```bash
+```ini
 ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"
 ```
 
-Set to `null` to only allow "known" registrars, or to a specific CA cert
-to trust only that specific signing authority.
+Set to `null` to only allow "known" registrars, or to a specific CA cert to
+trust only that specific signing authority.
 
 Multiple CAs can be trusted by specifying an array of certificates:
 
-```bash
+```ini
 ca[]="..."
 ca[]="..."
 ```
 
 See also the `strict-ssl` config.
 
-#### cafile
-
-* Default: `null`
-* Type: path
-
-A path to a file containing one or multiple Certificate Authority signing
-certificates. Similar to the `ca` setting, but allows for multiple CA's, as
-well as for the CA information to be stored in a file on disk.
-
-#### cache
-
-* Default: Windows: `%AppData%\npm-cache`, Posix: `~/.npm`
-* Type: path
-
-The location of npm's cache directory.  See [`npm cache`](/commands/npm-cache)
+#### `cache`
 
-#### cache-lock-stale
+* Default: Windows: `%LocalAppData%\npm-cache`, Posix: `~/.npm`
+* Type: Path
 
-* Default: 60000 (1 minute)
-* Type: Number
-
-The number of ms before cache folder lockfiles are considered stale.
+The location of npm's cache directory. See [`npm
+cache`](/commands/npm-cache)
 
-#### cache-lock-retries
-
-* Default: 10
-* Type: Number
+#### `cafile`
 
-Number of times to retry to acquire a lock on cache folder lockfiles.
-
-#### cache-lock-wait
-
-* Default: 10000 (10 seconds)
-* Type: Number
-
-Number of ms to wait for cache lock files to expire.
-
-#### cache-max
-
-* Default: Infinity
-* Type: Number
-
-**DEPRECATED**: This option has been deprecated in favor of `--prefer-online`.
-
-`--cache-max=0` is an alias for `--prefer-online`.
-
-#### cache-min
-
-* Default: 10
-* Type: Number
-
-**DEPRECATED**: This option has been deprecated in favor of `--prefer-offline`.
+* Default: null
+* Type: Path
 
-`--cache-min=9999 (or bigger)` is an alias for `--prefer-offline`.
+A path to a file containing one or multiple Certificate Authority signing
+certificates. Similar to the `ca` setting, but allows for multiple CA's, as
+well as for the CA information to be stored in a file on disk.
 
-#### call
+#### `call`
 
 * Default: ""
 * Type: String
@@ -306,154 +282,206 @@ custom command to be run along with the installed packages.
 npm exec --package yo --package generator-node --call "yo node"
 ```
 
-#### cert
 
-* Default: `null`
-* Type: String
+#### `cert`
 
-A client certificate to pass when accessing the registry.  Values should be in
-PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with newlines replaced by the string "\n". For example:
+* Default: null
+* Type: null or String
 
-```bash
+A client certificate to pass when accessing the registry. Values should be
+in PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with
+newlines replaced by the string "\n". For example:
+
+```ini
 cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"
 ```
 
-It is _not_ the path to a certificate file (and there is no "certfile" option).
+It is _not_ the path to a certificate file (and there is no "certfile"
+option).
 
-#### cidr
+#### `ci-name`
 
-* Default: `null`
-* Type: String, Array, null
+* Default: The name of the current CI system, or `null` when not on a known CI
+  platform.
+* Type: null or String
 
-This is a list of CIDR address to be used when configuring limited access tokens with the `npm token create` command.
+The name of a continuous integration system. If not set explicitly, npm will
+detect the current CI environment using the
+[`@npmcli/ci-detect`](http://npm.im/@npmcli/ci-detect) module.
 
-#### commit-hooks
+#### `cidr`
 
-* Default: `true`
-* Type: Boolean
+* Default: null
+* Type: null or String (can be set multiple times)
 
-Run git commit hooks when using the `npm version` command.
+This is a list of CIDR address to be used when configuring limited access
+tokens with the `npm token create` command.
 
-#### color
+#### `color`
 
-* Default: true
-* Type: Boolean or `"always"`
+* Default: true unless the NO_COLOR environ is set to something other than '0'
+* Type: "always" or Boolean
+
+If false, never shows colors. If `"always"` then always shows colors. If
+true, then only prints color codes for tty file descriptors.
 
-If false, never shows colors.  If `"always"` then always shows colors.
-If true, then only prints color codes for tty file descriptors.
+#### `commit-hooks`
 
-This option can also be changed using the environment: colors are
-disabled when the environment variable `NO_COLOR` is set to any value.
+* Default: true
+* Type: Boolean
+
+Run git commit hooks when using the `npm version` command.
 
-#### depth
+#### `depth`
 
-* Default: null
+* Default: `Infinity` if `--all` is set, otherwise `1`
 * Type: null or Number
 
 The depth to go when recursing packages for `npm ls`.
 
-To make this default to `Infinity` instead of `null`, set `--all`.
+If not set, `npm ls` will show only the immediate dependencies of the root
+project. If `--all` is set, then npm will show all dependencies by default.
 
-#### description
+#### `description`
 
 * Default: true
 * Type: Boolean
 
 Show the description in `npm search`
 
-#### dev
+#### `diff`
+
+* Default:
+* Type: String (can be set multiple times)
+
+Define arguments to compare in `npm diff`.
+
+#### `diff-dst-prefix`
+
+* Default: "b/"
+* Type: String
+
+Destination prefix to be used in `npm diff` output.
+
+#### `diff-ignore-all-space`
 
 * Default: false
 * Type: Boolean
 
-\[Deprecated\] Install `dev-dependencies` along with packages.
+Ignore whitespace when comparing lines in `npm diff`.
 
-#### dry-run
+#### `diff-name-only`
 
 * Default: false
 * Type: Boolean
 
-Indicates that you don't want npm to make any changes and that it should
-only report what it would have done.  This can be passed into any of the
-commands that modify your local installation, eg, `install`, `update`,
-`dedupe`, `uninstall`.  This is NOT currently honored by some network related
-commands, eg `dist-tags`, `owner`, etc.
+Prints only filenames when using `npm diff`.
 
-#### diff
+#### `diff-no-prefix`
 
-* Default: null
-* Type: String, Array, null
+* Default: false
+* Type: Boolean
 
-Define arguments to compare in `npm diff`.
+Do not show any source or destination prefix in `npm diff` output.
+
+Note: this causes `npm diff` to ignore the `--diff-src-prefix` and
+`--diff-dst-prefix` configs.
+
+#### `diff-src-prefix`
 
-#### diff-name-only
+* Default: "a/"
+* Type: String
+
+Source prefix to be used in `npm diff` output.
+
+#### `diff-text`
 
 * Default: false
 * Type: Boolean
 
-Prints only filenames when using `npm diff`.
+Treat all files as text in `npm diff`.
 
-#### diff-unified
+#### `diff-unified`
 
-* Type: number
-* Default: `3`
+* Default: 3
+* Type: Number
 
 The number of lines of context to print in `npm diff`.
 
-#### diff-ignore-all-space
+#### `dry-run`
 
-* Type: Boolean
 * Default: false
+* Type: Boolean
 
-Ignore whitespace when comparing lines in `npm diff.
+Indicates that you don't want npm to make any changes and that it should
+only report what it would have done. This can be passed into any of the
+commands that modify your local installation, eg, `install`, `update`,
+`dedupe`, `uninstall`, as well as `pack` and `publish`.
 
-#### diff-no-prefix
+Note: This is NOT honored by other network related commands, eg `dist-tags`,
+`owner`, etc.
+
+#### `editor`
+
+* Default: The EDITOR or VISUAL environment variables, or 'notepad.exe' on
+  Windows, or 'vim' on Unix systems
+* Type: String
+
+The command to run for `npm edit` and `npm config edit`.
+
+#### `engine-strict`
 
-* Type: Boolean
 * Default: false
+* Type: Boolean
 
-Do not show any source or destination prefix in `npm diff` output.
+If set to true, then npm will stubbornly refuse to install (or even consider
+installing) any package that claims to not be compatible with the current
+Node.js version.
 
-#### diff-src-prefix
+This can be overridden by setting the `--force` flag.
 
-* Type: String
-* Default: `"a/"`
+#### `fetch-retries`
 
-Source prefix to be used in `npm diff` output.
+* Default: 2
+* Type: Number
 
-#### diff-dst-prefix
+The "retries" config for the `retry` module to use when fetching packages
+from the registry.
 
-* Type: String
-* Default: `"b/"`
+npm will retry idempotent read requests to the registry in the case of
+network failures or 5xx HTTP errors.
 
-Destination prefix to be used in `npm diff` output.
+#### `fetch-retry-factor`
 
-#### diff-text
+* Default: 10
+* Type: Number
 
-* Alias: `-a`
-* Type: Boolean
-* Default: false
+The "factor" config for the `retry` module to use when fetching packages.
 
-Treat all files as text in `npm diff`.
+#### `fetch-retry-maxtimeout`
 
-#### editor
+* Default: 60000 (1 minute)
+* Type: Number
+
+The "maxTimeout" config for the `retry` module to use when fetching
+packages.
+
+#### `fetch-retry-mintimeout`
 
-* Default: `EDITOR` environment variable if set, or `"vi"` on Posix,
-  or `"notepad"` on Windows.
-* Type: path
+* Default: 10000 (10 seconds)
+* Type: Number
 
-The command to run for `npm edit` or `npm config edit`.
+The "minTimeout" config for the `retry` module to use when fetching
+packages.
 
-#### engine-strict
+#### `fetch-timeout`
 
-* Default: false
-* Type: Boolean
+* Default: 300000 (5 minutes)
+* Type: Number
 
-If set to true, then npm will stubbornly refuse to install (or even
-consider installing) any package that claims to not be compatible with
-the current Node.js version.
+The maximum amount of time to wait for HTTP requests to complete.
 
-#### force
+#### `force`
 
 * Default: false
 * Type: Boolean
@@ -467,17 +495,16 @@ mistakes, unnecessary performance degradation, and malicious input.
 * Allow installing packages that have an `engines` declaration requiring a
   different version of npm.
 * Allow installing packages that have an `engines` declaration requiring a
-  different version of `node`, even if `--engines-strict` is enabled.
+  different version of `node`, even if `--engine-strict` is enabled.
 * Allow `npm audit fix` to install modules outside your stated dependency
   range (including SemVer-major changes).
-* Allow a module to be installed as a direct dependency of itself.
 * Allow unpublishing all versions of a published package.
 * Allow conflicting peerDependencies to be installed in the root project.
 
 If you don't have a clear idea of what you want to do, it is strongly
 recommended that you do not use this option!
 
-#### foreground-scripts
+#### `foreground-scripts`
 
 * Default: false
 * Type: Boolean
@@ -486,249 +513,217 @@ Run all build scripts (ie, `preinstall`, `install`, and `postinstall`)
 scripts for installed packages in the foreground process, sharing standard
 input, output, and error with the main npm process.
 
-Note that this will generally make installs run slower, and be much
-noisier, but can be useful for debugging.
+Note that this will generally make installs run slower, and be much noisier,
+but can be useful for debugging.
 
-#### format-package-lock
+#### `format-package-lock`
 
 * Default: true
 * Type: Boolean
 
-Format `package-lock.json` or `npm-shrinkwrap.json` as a human readable file.
+Format `package-lock.json` or `npm-shrinkwrap.json` as a human readable
+file.
 
-#### fund
+#### `fund`
 
 * Default: true
 * Type: Boolean
 
 When "true" displays the message at the end of each `npm install`
-acknowledging the number of dependencies looking for funding.
-See [`npm fund`](/commands/npm-fund) for details.
-
-#### fetch-retries
-
-* Default: 2
-* Type: Number
-
-The "retries" config for the `retry` module to use when fetching
-packages from the registry.
-
-#### fetch-retry-factor
-
-* Default: 10
-* Type: Number
-
-The "factor" config for the `retry` module to use when fetching
-packages.
-
-#### fetch-retry-mintimeout
-
-* Default: 10000 (10 seconds)
-* Type: Number
-
-The "minTimeout" config for the `retry` module to use when fetching
-packages.
-
-#### fetch-retry-maxtimeout
-
-* Default: 60000 (1 minute)
-* Type: Number
-
-The "maxTimeout" config for the `retry` module to use when fetching
-packages.
-
-#### fetch-timeout
-
-* Default: 300000 (5 minutes)
-* Type: Number
-
-The maximum amount of time to wait for HTTP requests to complete.
+acknowledging the number of dependencies looking for funding. See [`npm
+fund`](/commands/npm-fund) for details.
 
-#### git
+#### `git`
 
-* Default: `"git"`
+* Default: "git"
 * Type: String
 
-The command to use for git commands.  If git is installed on the
-computer, but is not in the `PATH`, then set this to the full path to
-the git binary.
+The command to use for git commands. If git is installed on the computer,
+but is not in the `PATH`, then set this to the full path to the git binary.
 
-#### git-tag-version
+#### `git-tag-version`
 
-* Default: `true`
+* Default: true
 * Type: Boolean
 
 Tag the commit when using the `npm version` command.
 
-#### global
+#### `global`
 
 * Default: false
 * Type: Boolean
 
-Operates in "global" mode, so that packages are installed into the
-`prefix` folder instead of the current working directory.  See
+Operates in "global" mode, so that packages are installed into the `prefix`
+folder instead of the current working directory. See
 [folders](/configuring-npm/folders) for more on the differences in behavior.
 
-* packages are installed into the `{prefix}/lib/node_modules` folder, instead of the
-  current working directory.
+* packages are installed into the `{prefix}/lib/node_modules` folder, instead
+  of the current working directory.
 * bin files are linked to `{prefix}/bin`
 * man pages are linked to `{prefix}/share/man`
 
-#### globalconfig
-
-* Default: {prefix}/etc/npmrc
-* Type: path
-
-The config file to read for global config options.
-
-#### global-style
+#### `global-style`
 
 * Default: false
 * Type: Boolean
 
 Causes npm to install the package into your local `node_modules` folder with
-the same layout it uses with the global `node_modules` folder.  Only your
+the same layout it uses with the global `node_modules` folder. Only your
 direct dependencies will show in `node_modules` and everything they depend
-on will be flattened in their `node_modules` folders.  This obviously will
-eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling` will be
-preferred.
+on will be flattened in their `node_modules` folders. This obviously will
+eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling`
+will be preferred.
+
+#### `globalconfig`
+
+* Default: The global --prefix setting plus 'etc/npmrc'. For example,
+  '/usr/local/etc/npmrc'
+* Type: Path
 
-#### heading
+The config file to read for global config options.
+
+#### `heading`
 
-* Default: `"npm"`
+* Default: "npm"
 * Type: String
 
 The string that starts all the debugging log output.
 
-#### https-proxy
+#### `https-proxy`
 
 * Default: null
-* Type: url
+* Type: null or URL
 
 A proxy to use for outgoing https requests. If the `HTTPS_PROXY` or
 `https_proxy` or `HTTP_PROXY` or `http_proxy` environment variables are set,
-proxy settings will be honored by the underlying `request` library.
+proxy settings will be honored by the underlying `make-fetch-happen`
+library.
 
-#### if-present
+#### `if-present`
 
 * Default: false
 * Type: Boolean
 
-If true, npm will not exit with an error code when `run-script` is invoked for
-a script that isn't defined in the `scripts` section of `package.json`. This
-option can be used when it's desirable to optionally run a script when it's
-present and fail if the script fails. This is useful, for example, when running
-scripts that may only apply for some builds in an otherwise generic CI setup.
+If true, npm will not exit with an error code when `run-script` is invoked
+for a script that isn't defined in the `scripts` section of `package.json`.
+This option can be used when it's desirable to optionally run a script when
+it's present and fail if the script fails. This is useful, for example, when
+running scripts that may only apply for some builds in an otherwise generic
+CI setup.
 
-#### ignore-prepublish
+#### `ignore-scripts`
 
 * Default: false
 * Type: Boolean
 
-If true, npm will not run `prepublish` scripts.
+If true, npm does not run scripts specified in package.json files.
 
-#### ignore-scripts
+#### `include`
 
-* Default: false
-* Type: Boolean
+* Default:
+* Type: "prod", "dev", "optional", or "peer" (can be set multiple times)
 
-If true, npm does not run scripts specified in package.json files.
+Option that allows for defining which types of dependencies to install.
 
-#### include
+This is the inverse of `--omit=<type>`.
 
-* Default: `[prod|dev|optional|peer]`
-* Type: Array
+Dependency types specified in `--include` will not be omitted, regardless of
+the order in which omit/include are specified on the command-line.
 
-Option that allows for defining which types of dependencies to install.
+#### `include-staged`
 
-#### init-module
+* Default: false
+* Type: Boolean
 
-* Alias: `init.module`
-* Default: ~/.npm-init.js
-* Type: path
+Allow installing "staged" published packages, as defined by [npm RFC PR
+#92](https://github.com/npm/rfcs/pull/92).
 
-A module that will be loaded by the `npm init` command.  See the
-documentation for the
-[init-package-json](https://github.com/npm/init-package-json) module
-for more information, or [npm init](/commands/npm-init).
+This is experimental, and not implemented by the npm public registry.
 
-#### init-author-name
+#### `init-author-email`
 
-* Alias: `init.author.name`
 * Default: ""
 * Type: String
 
-The value `npm init` should use by default for the package author's name.
+The value `npm init` should use by default for the package author's email.
 
-#### init-author-email
+#### `init-author-name`
 
-* Alias: `init.author.email`
 * Default: ""
 * Type: String
 
-The value `npm init` should use by default for the package author's email.
+The value `npm init` should use by default for the package author's name.
 
-#### init-author-url
+#### `init-author-url`
 
-* Alias: `init.author.url`
 * Default: ""
-* Type: String
+* Type: "" or URL
 
-The value `npm init` should use by default for the package author's homepage.
+The value `npm init` should use by default for the package author's
+homepage.
 
-#### init-license
+#### `init-license`
 
-* Alias: `init.license`
 * Default: "ISC"
 * Type: String
 
 The value `npm init` should use by default for the package license.
 
-#### init-version
+#### `init-module`
+
+* Default: "~/.npm-init.js"
+* Type: Path
+
+A module that will be loaded by the `npm init` command. See the
+documentation for the
+[init-package-json](https://github.com/npm/init-package-json) module for
+more information, or [npm init](/commands/npm-init).
+
+#### `init-version`
 
-* Alias: `init.version`
 * Default: "1.0.0"
-* Type: semver
+* Type: SemVer string
 
-The value that `npm init` should use by default for the package
-version number, if not already set in package.json.
+The value that `npm init` should use by default for the package version
+number, if not already set in package.json.
 
-#### json
+#### `json`
 
 * Default: false
 * Type: Boolean
 
 Whether or not to output JSON data, rather than the normal output.
 
-This feature is currently experimental, and the output data structures for many
-commands is either not implemented in JSON yet, or subject to change.  Only the
-output from `npm ls --json` and `npm search --json` are currently valid.
+This feature is currently experimental, and the output data structures for
+many commands is either not implemented in JSON yet, or subject to change.
+Only the output from `npm ls --json` and `npm search --json` are currently
+valid.
 
-#### key
+#### `key`
 
-* Default: `null`
-* Type: String
+* Default: null
+* Type: null or String
 
-A client key to pass when accessing the registry.  Values should be in PEM
+A client key to pass when accessing the registry. Values should be in PEM
 format with newlines replaced by the string "\n". For example:
 
-```json
+```ini
 key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"
 ```
 
 It is _not_ the path to a key file (and there is no "keyfile" option).
 
-#### legacy-bundling
+#### `legacy-bundling`
 
 * Default: false
 * Type: Boolean
 
 Causes npm to install the package such that versions of npm prior to 1.4,
-such as the one included with node 0.8, can install the package.  This
+such as the one included with node 0.8, can install the package. This
 eliminates all automatic deduping. If used with `global-style` this option
 will be preferred.
 
-#### legacy-peer-deps
+#### `legacy-peer-deps`
 
 * Default: false
 * Type: Boolean
@@ -736,9 +731,8 @@ will be preferred.
 Causes npm to completely ignore `peerDependencies` when building a package
 tree, as in npm versions 3 through 6.
 
-If a package cannot be installed because of overly strict
-`peerDependencies` that collide, it provides a way to move forward
-resolving the situation.
+If a package cannot be installed because of overly strict `peerDependencies`
+that collide, it provides a way to move forward resolving the situation.
 
 This differs from `--omit=peer`, in that `--omit=peer` will avoid unpacking
 `peerDependencies` on disk, but will still design a tree such that
@@ -747,7 +741,7 @@ This differs from `--omit=peer`, in that `--omit=peer` will avoid unpacking
 Use of `legacy-peer-deps` is not recommended, as it will not enforce the
 `peerDependencies` contract that meta-dependencies may rely on.
 
-#### link
+#### `link`
 
 * Default: false
 * Type: Boolean
@@ -755,57 +749,57 @@ Use of `legacy-peer-deps` is not recommended, as it will not enforce the
 If true, then local installs will link if there is a suitable globally
 installed package.
 
-Note that this means that local installs can cause things to be
-installed into the global space at the same time.  The link is only done
-if one of the two conditions are met:
+Note that this means that local installs can cause things to be installed
+into the global space at the same time. The link is only done if one of the
+two conditions are met:
 
 * The package is not already installed globally, or
-* the globally installed version is identical to the version that is
-  being installed locally.
+* the globally installed version is identical to the version that is being
+  installed locally.
 
-#### local-address
+#### `local-address`
 
-* Default: undefined
+* Default: null
 * Type: IP Address
 
-The IP address of the local interface to use when making connections
-to the npm registry.  Must be IPv4 in versions of Node prior to 0.12.
+The IP address of the local interface to use when making connections to the
+npm registry. Must be IPv4 in versions of Node prior to 0.12.
 
-#### loglevel
+#### `loglevel`
 
 * Default: "notice"
-* Type: String
-* Values: "silent", "error", "warn", "notice", "http", "timing", "info",
-  "verbose", "silly"
+* Type: "silent", "error", "warn", "notice", "http", "timing", "info",
+  "verbose", or "silly"
 
-What level of logs to report.  On failure, *all* logs are written to
+What level of logs to report. On failure, *all* logs are written to
 `npm-debug.log` in the current working directory.
 
-Any logs of a higher level than the setting are shown. The default is "notice".
+Any logs of a higher level than the setting are shown. The default is
+"notice".
 
-#### logs-max
+#### `logs-max`
 
 * Default: 10
 * Type: Number
 
 The maximum number of log files to store.
 
-#### long
+#### `long`
 
 * Default: false
 * Type: Boolean
 
 Show extended information in `npm ls` and `npm search`.
 
-#### maxsockets
+#### `maxsockets`
 
-* Default: 50
+* Default: Infinity
 * Type: Number
 
 The maximum number of connections to use per origin (protocol/host/port
-combination). Passed to the `http` `Agent` used to make the request.
+combination).
 
-#### message
+#### `message`
 
 * Default: "%s"
 * Type: String
@@ -814,73 +808,83 @@ Commit message which is used by `npm version` when creating version commit.
 
 Any "%s" in the message will be replaced with the version number.
 
-#### node-options
+#### `node-options`
 
 * Default: null
-* Type: String
+* Type: null or String
 
 Options to pass through to Node.js via the `NODE_OPTIONS` environment
-variable.  This does not impact how npm itself is executed but it does
-impact how lifecycle scripts are called.
+variable. This does not impact how npm itself is executed but it does impact
+how lifecycle scripts are called.
 
-#### node-version
+#### `node-version`
 
-* Default: process.version
-* Type: semver or false
+* Default: Node.js `process.version` value
+* Type: SemVer string
 
-The node version to use when checking a package's `engines` map.
+The node version to use when checking a package's `engines` setting.
 
-#### noproxy
+#### `noproxy`
 
-* Default: null
-* Type: String or Array
+* Default: The value of the NO_PROXY environment variable
+* Type: String (can be set multiple times)
 
-A comma-separated string or an array of domain extensions that a proxy should not be used for.
+Domain extensions that should bypass any proxies.
 
-#### offline
+Also accepts a comma-delimited string.
 
-* Default: false
-* Type: Boolean
+#### `npm-version`
 
-Force offline mode: no network requests will be done during install. To allow
-the CLI to fill in missing cache data, see `--prefer-offline`.
+* Default: Output of `npm --version`
+* Type: SemVer string
 
-#### only
+The npm version to use when checking a package's `engines` setting.
 
-* Default: null
-* Type: String
+#### `offline`
+
+* Default: false
+* Type: Boolean
 
-When "dev" or "development" and running local `npm install` without any
-arguments, only devDependencies (and their dependencies) are installed.
+Force offline mode: no network requests will be done during install. To
+allow the CLI to fill in missing cache data, see `--prefer-offline`.
 
-When "dev" or "development" and running local `npm ls`, `npm outdated`, or
-`npm update`, is an alias for `--dev`.
+#### `omit`
 
-When "prod" or "production" and running local `npm install` without any
-arguments, only non-devDependencies (and their dependencies) are
-installed.
+* Default: 'dev' if the NODE_ENV environment variable is set to 'production',
+  otherwise empty.
+* Type: "dev", "optional", or "peer" (can be set multiple times)
 
-When "prod" or "production" and running local `npm ls`, `npm outdated`, or
-`npm update`, is an alias for `--production`.
+Dependency types to omit from the installation tree on disk.
 
-#### optional
+Note that these dependencies _are_ still resolved and added to the
+`package-lock.json` or `npm-shrinkwrap.json` file. They are just not
+physically installed on disk.
 
-* Default: true
-* Type: Boolean
+If a package type appears in both the `--include` and `--omit` lists, then
+it will be included.
 
-Attempt to install packages in the `optionalDependencies` object.  Note
-that if these packages fail to install, the overall installation
-process is not aborted.
+If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment
+variable will be set to `'production'` for all lifecycle scripts.
 
-#### otp
+#### `otp`
 
 * Default: null
-* Type: Number
+* Type: null or String
 
-This is a one-time password from a two-factor authenticator.  It's needed
+This is a one-time password from a two-factor authenticator. It's needed
 when publishing or changing package permissions with `npm access`.
 
-#### package-lock
+If not set, and a registry response fails with a challenge for a one-time
+password, npm will prompt on the command line for one.
+
+#### `package`
+
+* Default:
+* Type: String (can be set multiple times)
+
+The package to install for [`npm exec`](/commands/npm-exec)
+
+#### `package-lock`
 
 * Default: true
 * Type: Boolean
@@ -889,75 +893,63 @@ If set to false, then ignore `package-lock.json` files when installing. This
 will also prevent _writing_ `package-lock.json` if `save` is true.
 
 When package package-locks are disabled, automatic pruning of extraneous
-modules will also be disabled.  To remove extraneous modules with
+modules will also be disabled. To remove extraneous modules with
 package-locks disabled use `npm prune`.
 
-This option is an alias for `--shrinkwrap`.
-
-#### package-lock-only
+#### `package-lock-only`
 
 * Default: false
 * Type: Boolean
 
-If set to true, it will update only the `package-lock.json`,
-instead of checking `node_modules` and downloading dependencies.
+If set to true, it will update only the `package-lock.json`, instead of
+checking `node_modules` and downloading dependencies.
 
-#### parseable
+#### `parseable`
 
 * Default: false
 * Type: Boolean
 
-Output parseable results from commands that write to
-standard output. For `npm search`, this will be tab-separated table format.
+Output parseable results from commands that write to standard output. For
+`npm search`, this will be tab-separated table format.
 
-#### prefer-offline
+#### `prefer-offline`
 
 * Default: false
 * Type: Boolean
 
 If true, staleness checks for cached data will be bypassed, but missing data
-will be requested from the server. To force full offline mode, use `--offline`.
+will be requested from the server. To force full offline mode, use
+`--offline`.
 
-This option is effectively equivalent to `--cache-min=9999999`.
-
-#### prefer-online
+#### `prefer-online`
 
 * Default: false
 * Type: Boolean
 
-If true, staleness checks for cached data will be forced, making the CLI look
-for updates immediately even for fresh package data.
+If true, staleness checks for cached data will be forced, making the CLI
+look for updates immediately even for fresh package data.
 
-#### prefix
+#### `prefix`
 
-* Default: see [folders](/configuring-npm/folders)
-* Type: path
+* Default: In global mode, the folder where the node executable is installed.
+  In local mode, the nearest parent folder containing either a package.json
+  file or a node_modules folder.
+* Type: Path
 
-The location to install global items.  If set on the command line, then
-it forces non-global commands to run in the specified folder.
+The location to install global items. If set on the command line, then it
+forces non-global commands to run in the specified folder.
 
-#### preid
+#### `preid`
 
 * Default: ""
 * Type: String
 
-The "prerelease identifier" to use as a prefix for the "prerelease" part of a
-semver. Like the `rc` in `1.2.0-rc.8`.
-
-#### production
-
-* Default: false
-* Type: Boolean
-
-Set to true to run in "production" mode.
+The "prerelease identifier" to use as a prefix for the "prerelease" part of
+a semver. Like the `rc` in `1.2.0-rc.8`.
 
-1. devDependencies are not installed at the topmost level when running
-   local `npm install` without any arguments.
-2. Set the NODE_ENV="production" for lifecycle scripts.
+#### `progress`
 
-#### progress
-
-* Default: true, unless TRAVIS or CI env vars set.
+* Default: `true` unless running in a known CI system
 * Type: Boolean
 
 When set to `true`, npm will display a progress bar during time intensive
@@ -965,56 +957,48 @@ operations, if `process.stderr` is a TTY.
 
 Set to `false` to suppress the progress bar.
 
-#### proxy
+#### `proxy`
 
 * Default: null
-* Type: url
+* Type: null, false, or URL
 
 A proxy to use for outgoing http requests. If the `HTTP_PROXY` or
-`http_proxy` environment variables are set, proxy settings will be
-honored by the underlying `request` library.
+`http_proxy` environment variables are set, proxy settings will be honored
+by the underlying `request` library.
 
-#### read-only
+#### `read-only`
 
 * Default: false
 * Type: Boolean
 
-This is used to mark a token as unable to publish when configuring limited access tokens with the `npm token create` command.
+This is used to mark a token as unable to publish when configuring limited
+access tokens with the `npm token create` command.
 
-#### rebuild-bundle
+#### `rebuild-bundle`
 
 * Default: true
 * Type: Boolean
 
 Rebuild bundled dependencies after installation.
 
-#### registry
-
-* Default: https://registry.npmjs.org/
-* Type: url
-
-The base URL of the npm package registry.
+#### `registry`
 
-#### rollback
-
-* Default: true
-* Type: Boolean
+* Default: "https://registry.npmjs.org/"
+* Type: URL
 
-Remove failed installs.
+The base URL of the npm registry.
 
-#### save
+#### `save`
 
 * Default: true
 * Type: Boolean
 
 Save installed packages to a package.json file as dependencies.
 
-When used with the `npm rm` command, it removes it from the `dependencies`
-object.
+When used with the `npm rm` command, removes the dependency from
+package.json.
 
-Only works if there is already a package.json file present.
-
-#### save-bundle
+#### `save-bundle`
 
 * Default: false
 * Type: Boolean
@@ -1023,120 +1007,94 @@ If a package would be saved at install time by the use of `--save`,
 `--save-dev`, or `--save-optional`, then also put it in the
 `bundleDependencies` list.
 
-When used with the `npm rm` command, it removes it from the
-bundledDependencies list.
+Ignore if `--save-peer` is set, since peerDependencies cannot be bundled.
 
-#### save-prod
+#### `save-dev`
 
 * Default: false
 * Type: Boolean
 
-Makes sure that a package will be saved into `dependencies` specifically. This
-is useful if a package already exists in `devDependencies` or
-`optionalDependencies`, but you want to move it to be a production dep. This is
-also the default behavior if `--save` is true, and neither `--save-dev` or
-`--save-optional` are true.
+Save installed packages to a package.json file as `devDependencies`.
 
-#### save-dev
+#### `save-exact`
 
 * Default: false
 * Type: Boolean
 
-Save installed packages to a package.json file as `devDependencies`.
-
-When used with the `npm rm` command, it removes it from the
-`devDependencies` object.
-
-Only works if there is already a package.json file present.
+Dependencies saved to package.json will be configured with an exact version
+rather than using npm's default semver range operator.
 
-#### save-exact
+#### `save-optional`
 
 * Default: false
 * Type: Boolean
 
-Dependencies saved to package.json using `--save`, `--save-dev` or
-`--save-optional` will be configured with an exact version rather than
-using npm's default semver range operator.
+Save installed packages to a package.json file as `optionalDependencies`.
 
-#### save-optional
+#### `save-peer`
 
 * Default: false
 * Type: Boolean
 
-Save installed packages to a package.json file as
-optionalDependencies.
-
-When used with the `npm rm` command, it removes it from the
-`devDependencies` object.
+Save installed packages. to a package.json file as `peerDependencies`
 
-Only works if there is already a package.json file present.
+#### `save-prefix`
 
-#### save-prefix
-
-* Default: '^'
+* Default: "^"
 * Type: String
 
 Configure how versions of packages installed to a package.json file via
 `--save` or `--save-dev` get prefixed.
 
-For example if a package has version `1.2.3`, by default its version is
-set to `^1.2.3` which allows minor upgrades for that package, but after
-`npm config set save-prefix='~'` it would be set to `~1.2.3` which only allows
+For example if a package has version `1.2.3`, by default its version is set
+to `^1.2.3` which allows minor upgrades for that package, but after `npm
+config set save-prefix='~'` it would be set to `~1.2.3` which only allows
 patch upgrades.
 
-#### scope
-
-* Default: the scope of the current project, if any, or ""
-* Type: String
-
-Associate an operation with a scope for a scoped registry. Useful when logging
-in to a private registry for the first time:
-`npm login --scope=@organization --registry=registry.organization.com`, which
-will cause `@organization` to be mapped to the registry for future installation
-of packages specified according to the pattern `@organization/package`.
+#### `save-prod`
 
-#### script-shell
+* Default: false
+* Type: Boolean
 
-* Default: `null`
-* Type: path
+Save installed packages into `dependencies` specifically. This is useful if
+a package already exists in `devDependencies` or `optionalDependencies`, but
+you want to move it to be a non-optional production dependency.
 
-The shell to use for scripts run with the `npm run` command.
+This is the default behavior if `--save` is true, and neither `--save-dev`
+or `--save-optional` are true.
 
-#### scripts-prepend-node-path
+#### `scope`
 
-* Default: "warn-only"
-* Type: Boolean, `"auto"` or `"warn-only"`
+* Default: the scope of the current project, if any, or ""
+* Type: String
 
-If set to `true`, add the directory in which the current `node` executable
-resides to the `PATH` environment variable when running scripts,
-even if that means that `npm` will invoke a different `node` executable than
-the one which it is running.
+Associate an operation with a scope for a scoped registry.
 
-If set to `false`, never modify `PATH` with that.
+Useful when logging in to a private registry for the first time:
 
-If set to `"warn-only"`, never modify `PATH` but print a warning if `npm` thinks
-that you may want to run it with `true`, e.g. because the `node` executable
-in the `PATH` is not the one `npm` was invoked with.
+```bash
+npm login --scope=@mycorp --registry=https://registry.mycorp.com
+```
 
-If set to `auto`, only add that directory to the `PATH` environment variable
-if the `node` executable with which `npm` was invoked and the one that is found
-first on the `PATH` are different.
+This will cause `@mycorp` to be mapped to the registry for future
+installation of packages specified according to the pattern
+`@mycorp/package`.
 
-#### searchexclude
+#### `script-shell`
 
-* Default: ""
-* Type: String
+* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows
+* Type: null or String
 
-Space-separated options that limit the results from search.
+The shell to use for scripts run with the `npm run` command.
 
-#### searchopts
+#### `searchexclude`
 
 * Default: ""
 * Type: String
 
-Space-separated options that are always passed to search.
+Space-separated options that limit the results from search.
 
-#### searchlimit
+#### `searchlimit`
 
 * Default: 20
 * Type: Number
@@ -1144,33 +1102,30 @@ Space-separated options that are always passed to search.
 Number of items to limit search results to. Will not apply at all to legacy
 searches.
 
-#### searchstaleness
+#### `searchopts`
 
-* Default: 900 (15 minutes)
+* Default: ""
+* Type: String
+
+Space-separated options that are always passed to search.
+
+#### `searchstaleness`
+
+* Default: 900
 * Type: Number
 
 The age of the cache, in seconds, before another registry request is made if
 using legacy search endpoint.
 
-#### shell
+#### `shell`
 
-* Default: SHELL environment variable, or "bash" on Posix, or "cmd" on
+* Default: SHELL environment variable, or "bash" on Posix, or "cmd.exe" on
   Windows
-* Type: path
+* Type: String
 
 The shell to run for the `npm explore` command.
 
-#### shrinkwrap
-
-* Default: true
-* Type: Boolean
-
-If set to false, then ignore `npm-shrinkwrap.json` files when installing. This
-will also prevent _writing_ `npm-shrinkwrap.json` if `save` is true.
-
-This option is an alias for `--package-lock`.
-
-#### sign-git-commit
+#### `sign-git-commit`
 
 * Default: false
 * Type: Boolean
@@ -1178,36 +1133,21 @@ This option is an alias for `--package-lock`.
 If set to true, then the `npm version` command will commit the new package
 version using `-S` to add a signature.
 
-Note that git requires you to have set up GPG keys in your git configs
-for this to work properly.
+Note that git requires you to have set up GPG keys in your git configs for
+this to work properly.
 
-#### sign-git-tag
+#### `sign-git-tag`
 
 * Default: false
 * Type: Boolean
 
-If set to true, then the `npm version` command will tag the version
-using `-s` to add a signature.
-
-Note that git requires you to have set up GPG keys in your git configs
-for this to work properly.
-
-#### sso-poll-frequency
-
-* Default: 500
-* Type: Number
-
-When used with SSO-enabled `auth-type`s, configures how regularly the registry
-should be polled while the user is completing authentication.
-
-#### sso-type
-
-* Default: 'oauth'
-* Type: 'oauth', 'saml', or null
+If set to true, then the `npm version` command will tag the version using
+`-s` to add a signature.
 
-If `--auth-type=sso`, the type of SSO type to use.
+Note that git requires you to have set up GPG keys in your git configs for
+this to work properly.
 
-#### strict-peer-deps
+#### `strict-peer-deps`
 
 * Default: false
 * Type: Boolean
@@ -1217,145 +1157,317 @@ conflicting `peerDependencies` will be treated as an install failure, even
 if npm could reasonably guess the appropriate resolution based on non-peer
 dependency relationships.
 
-By default, conflicting `peerDependencies` in the dependency graph will be
-resolved using the nearest non-peer dependency specification, even if doing
-so will result in some packages receiving a peer dependency outside the
-range set in their package's `peerDependencies` object.  When such and
-override is performed, a warning is printed, explaining the conflict and
-the packages involved.  If `--strict-peer-deps` is set, then the warning is
-treated as a failure.
+By default, conflicting `peerDependencies` deep in the dependency graph will
+be resolved using the nearest non-peer dependency specification, even if
+doing so will result in some packages receiving a peer dependency outside
+the range set in their package's `peerDependencies` object.
+
+When such and override is performed, a warning is printed, explaining the
+conflict and the packages involved. If `--strict-peer-deps` is set, then
+this warning is treated as a failure.
 
-#### strict-ssl
+#### `strict-ssl`
 
 * Default: true
 * Type: Boolean
 
-Whether or not to do SSL key validation when making requests to the
-registry via https.
+Whether or not to do SSL key validation when making requests to the registry
+via https.
 
 See also the `ca` config.
 
-#### tag
+#### `tag`
 
-* Default: latest
+* Default: "latest"
 * Type: String
 
-If you ask npm to install a package and don't tell it a specific version, then
-it will install the specified tag.
+If you ask npm to install a package and don't tell it a specific version,
+then it will install the specified tag.
 
-Also the tag that is added to the package@version specified by the `npm
-tag` command, if no explicit tag is given.
+Also the tag that is added to the package@version specified by the `npm tag`
+command, if no explicit tag is given.
 
-#### tag-version-prefix
+#### `tag-version-prefix`
 
-* Default: `"v"`
+* Default: "v"
 * Type: String
 
 If set, alters the prefix used when tagging a new version when performing a
-version increment using  `npm-version`. To remove the prefix altogether, set it
-to the empty string: `""`.
+version increment using `npm-version`. To remove the prefix altogether, set
+it to the empty string: `""`.
 
-Because other tools may rely on the convention that npm version tags look like
-`v1.0.0`, _only use this property if it is absolutely necessary_. In
+Because other tools may rely on the convention that npm version tags look
+like `v1.0.0`, _only use this property if it is absolutely necessary_. In
 particular, use care when overriding this setting for public packages.
 
-#### timing
+#### `timing`
 
-* Default: `false`
+* Default: false
 * Type: Boolean
 
 If true, writes an `npm-debug` log to `_logs` and timing information to
-`_timing.json`, both in your cache.  `_timing.json` is a newline delimited
-list of JSON objects.  You can quickly view it with this
-[json](https://www.npmjs.com/package/json) command line:
-`json -g < ~/.npm/_timing.json`.
+`_timing.json`, both in your cache, even if the command completes
+successfully. `_timing.json` is a newline delimited list of JSON objects.
 
-#### tmp
+You can quickly view it with this [json](https://npm.im/json) command line:
+`npm exec -- json -g < ~/.npm/_timing.json`.
 
-* Default: TMPDIR environment variable, or "/tmp"
-* Type: path
+#### `umask`
 
-Where to store temporary files and folders.  All temp files are deleted
-on success, but left behind on failure for forensic purposes.
+* Default: 0
+* Type: Octal numeric string in range 0000..0777 (0..511)
+
+The "umask" value to use when setting the file creation mode on files and
+folders.
+
+Folders and executables are given a mode which is `0o777` masked against
+this value. Other files are given a mode which is `0o666` masked against
+this value.
 
-#### unicode
+Note that the underlying system will _also_ apply its own umask value to
+files and folders that are created, and npm does not circumvent this, but
+rather adds the `--umask` config to it.
 
-* Default: false on windows, true on mac/unix systems with a unicode locale
+Thus, the effective default umask value on most POSIX systems is 0o22,
+meaning that folders and executables are created with a mode of 0o755 and
+other files are created with a mode of 0o644.
+
+#### `unicode`
+
+* Default: false on windows, true on mac/unix systems with a unicode locale,
+  as defined by the LC_ALL, LC_CTYPE, or LANG environment variables.
 * Type: Boolean
 
-When set to true, npm uses unicode characters in the tree output.  When
-false, it uses ascii characters to draw trees.
+When set to true, npm uses unicode characters in the tree output. When
+false, it uses ascii characters instead of unicode glyphs.
 
-#### update-notifier
+#### `update-notifier`
 
 * Default: true
 * Type: Boolean
 
-Set to false to suppress the update notification when using an older
-version of npm than the latest.
+Set to false to suppress the update notification when using an older version
+of npm than the latest.
 
-#### usage
+#### `usage`
 
 * Default: false
 * Type: Boolean
 
-Set to show short usage output (like the -H output)
-instead of complete help when doing [`npm help`](/commands/npm-help).
-
-#### userconfig
+Show short usage output about the command specified.
 
-* Default: ~/.npmrc
-* Type: path
+#### `user-agent`
 
-The location of user-level configuration settings.
-
-#### umask
+* Default: "npm/{npm-version} node/{node-version} {platform} {arch} {ci}"
+* Type: String
 
-* Default: 022
-* Type: Octal numeric string in range 0000..0777 (0..511)
+Sets the User-Agent request header. The following fields are replaced with
+their actual counterparts:
 
-The "umask" value to use when setting the file creation mode on files
-and folders.
+* `{npm-version}` - The npm version in use
+* `{node-version}` - The Node.js version in use
+* `{platform}` - The value of `process.platform`
+* `{arch}` - The value of `process.arch`
+* `{ci}` - The value of the `ci-name` config, if set, prefixed with `ci/`, or
+  an empty string if `ci-name` is empty.
 
-Folders and executables are given a mode which is `0777` masked against
-this value.  Other files are given a mode which is `0666` masked against
-this value.  Thus, the defaults are `0755` and `0644` respectively.
+#### `userconfig`
 
-#### user-agent
+* Default: "~/.npmrc"
+* Type: Path
 
-* Default: node/{process.version} {process.platform} {process.arch}
-* Type: String
+The location of user-level configuration settings.
 
-Sets a User-Agent to the request header
+This may be overridden by the `npm_config_userconfig` environment variable
+or the `--userconfig` command line option, but may _not_ be overridden by
+settings in the `globalconfig` file.
 
-#### version
+#### `version`
 
 * Default: false
-* Type: boolean
+* Type: Boolean
 
 If true, output the npm version and exit successfully.
 
 Only relevant when specified explicitly on the command line.
 
-#### versions
+#### `versions`
 
 * Default: false
-* Type: boolean
+* Type: Boolean
 
-If true, output the npm version as well as node's `process.versions` map, and
-exit successfully.
+If true, output the npm version as well as node's `process.versions` map and
+the version in the current working directory's `package.json` file if one
+exists, and exit successfully.
 
 Only relevant when specified explicitly on the command line.
 
-#### viewer
+#### `viewer`
 
 * Default: "man" on Posix, "browser" on Windows
-* Type: path
+* Type: String
 
 The program to use to view help content.
 
 Set to `"browser"` to view html help content in the default web browser.
 
+#### `yes`
+
+* Default: false
+* Type: Boolean
+
+Automatically answer "yes" to any prompts that npm might print on the
+command line.
+
+#### `also`
+
+* Default: null
+* Type: null, "dev", or "development"
+* DEPRECATED: Please use --include=dev instead.
+
+When set to `dev` or `development`, this is an alias for `--include=dev`.
+
+#### `auth-type`
+
+* Default: "legacy"
+* Type: "legacy", "sso", "saml", or "oauth"
+* DEPRECATED: This method of SSO/SAML/OAuth is deprecated and will be removed
+  in a future version of npm in favor of web-based login.
+
+What authentication strategy to use with `adduser`/`login`.
+
+#### `cache-max`
+
+* Default: Infinity
+* Type: Number
+* DEPRECATED: This option has been deprecated in favor of `--prefer-online`
+
+`--cache-max=0` is an alias for `--prefer-online`
+
+#### `cache-min`
+
+* Default: 0
+* Type: Number
+* DEPRECATED: This option has been deprecated in favor of `--prefer-offline`.
+
+`--cache-min=9999 (or bigger)` is an alias for `--prefer-offline`.
+
+#### `init.author.email`
+
+* Default: ""
+* Type: String
+* DEPRECATED: Use `--init-author-email` instead.
+
+Alias for `--init-author-email`
+
+#### `init.author.name`
+
+* Default: ""
+* Type: String
+* DEPRECATED: Use `--init-author-name` instead.
+
+Alias for `--init-author-name`
+
+#### `init.author.url`
+
+* Default: ""
+* Type: "" or URL
+* DEPRECATED: Use `--init-author-url` instead.
+
+Alias for `--init-author-url`
+
+#### `init.license`
+
+* Default: "ISC"
+* Type: String
+* DEPRECATED: Use `--init-license` instead.
+
+Alias for `--init-license`
+
+#### `init.module`
+
+* Default: "~/.npm-init.js"
+* Type: Path
+* DEPRECATED: Use `--init-module` instead.
+
+Alias for `--init-module`
+
+#### `init.version`
+
+* Default: "1.0.0"
+* Type: SemVer string
+* DEPRECATED: Use `--init-version` instead.
+
+Alias for `--init-version`
+
+#### `only`
+
+* Default: null
+* Type: null, "prod", or "production"
+* DEPRECATED: Use `--omit=dev` to omit dev dependencies from the install.
+
+When set to `prod` or `production`, this is an alias for `--omit=dev`.
+
+#### `optional`
+
+* Default: null
+* Type: null or Boolean
+* DEPRECATED: Use `--omit=optional` to exclude optional dependencies, or
+  `--include=optional` to include them.
+
+Default value does install optional deps unless otherwise omitted.
+
+Alias for --include=optional or --omit=optional
+
+#### `production`
+
+* Default: false
+* Type: Boolean
+* DEPRECATED: Use `--omit=dev` instead.
+
+Alias for `--omit=dev`
+
+#### `shrinkwrap`
+
+* Default: true
+* Type: Boolean
+* DEPRECATED: Use the --package-lock setting instead.
+
+Alias for --package-lock
+
+#### `sso-poll-frequency`
+
+* Default: 500
+* Type: Number
+* DEPRECATED: The --auth-type method of SSO/SAML/OAuth will be removed in a
+  future version of npm in favor of web-based login.
+
+When used with SSO-enabled `auth-type`s, configures how regularly the
+registry should be polled while the user is completing authentication.
+
+#### `sso-type`
+
+* Default: "oauth"
+* Type: null, "oauth", or "saml"
+* DEPRECATED: The --auth-type method of SSO/SAML/OAuth will be removed in a
+  future version of npm in favor of web-based login.
+
+If `--auth-type=sso`, the type of SSO type to use.
+
+#### `tmp`
+
+* Default: The value returned by the Node.js `os.tmpdir()` method
+  <https://nodejs.org/api/os.html#os_os_tmpdir>
+* Type: Path
+* DEPRECATED: This setting is no longer used. npm stores temporary files in a
+  special location in the cache, and they are managed by
+  [`cacache`](http://npm.im/cacache).
+
+Historically, the location where temporary files were stored. No longer
+relevant.
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
+
 ### See also
 
 * [npm config](/commands/npm-config)
diff --git a/scripts/config-doc.js b/scripts/config-doc.js
new file mode 100644
index 0000000000000..9bb4628898028
--- /dev/null
+++ b/scripts/config-doc.js
@@ -0,0 +1,50 @@
+const { shorthands, describeAll } = require('../lib/utils/config/index.js')
+const { writeFileSync, readFileSync } = require('fs')
+const { resolve } = require('path')
+const configDoc = resolve(__dirname, '../docs/content/using-npm/config.md')
+
+const addBetweenTags = (doc, startTag, endTag, body) => {
+  const startSplit = doc.split(startTag)
+  if (startSplit.length !== 2)
+    throw new Error('Did not find exactly one start tag')
+
+  const endSplit = startSplit[1].split(endTag)
+  if (endSplit.length !== 2)
+    throw new Error('Did not find exactly one end tag')
+
+  return [
+    startSplit[0],
+    startTag,
+    '\n<!-- automatically generated, do not edit manually -->\n',
+    body,
+    '\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 addShorthands = doc => {
+  const startTag = '<!-- AUTOGENERATED CONFIG SHORTHANDS START -->'
+  const endTag = '<!-- AUTOGENERATED CONFIG SHORTHANDS END -->'
+  const body = Object.entries(shorthands)
+    .sort(([shorta, expansiona], [shortb, expansionb]) => {
+      // sort by what they're short FOR
+      return expansiona.join(' ').localeCompare(expansionb.join(' ')) ||
+        shorta.localeCompare(shortb)
+    })
+    .map(([short, expansion]) => {
+    const dash = short.length === 1 ? '-' : '--'
+    return `* \`${dash}${short}\`: \`${expansion.join(' ')}\``
+  }).join('\n')
+  return addBetweenTags(doc, startTag, endTag, body)
+}
+
+const doc = readFileSync(configDoc, 'utf8')
+writeFileSync(configDoc, addDescriptions(addShorthands(doc)))
+console.log(`updated docs/content/using-npm/config.md`)