audit: add subcommand to automatically fix vulns (#20569)

PR-URL: https://github.com/npm/npm/pull/20569
Credit: @zkat
Reviewed-By: @iarna

1 files changed, 54 insertions, 3 deletions

diff --git a/doc/cli/npm-audit.md b/doc/cli/npm-audit.md
index 63fdf7666..3bb13259d 100644
--- a/doc/cli/npm-audit.md
+++ b/doc/cli/npm-audit.md
@@ -4,14 +4,64 @@ npm-audit(1) -- Run a security audit
 ## SYNOPSIS
 
     npm audit [--json]
+    npm audit fix [--force|--package-lock-only|--dry-run|--production|--only=dev]
 
-## DESCRIPTION 
+## EXAMPLES
+
+Scan your project for vulnerabilities and automatically install any compatible
+updates to vulnerable dependencies:
+```
+$ npm audit fix
+```
+
+Run `audit fix` without modifying `node_modules`, but still updating the
+pkglock:
+```
+$ npm audit fix --package-lock-only
+```
+
+Skip updating `devDependencies`:
+```
+$ npm audit fix --only=prod
+```
+
+Have `audit fix` install semver-major updates to toplevel dependencies, not just
+semver-compatible ones:
+```
+$ npm audit fix --force
+```
+
+Do a dry run to get an idea of what `audit fix` will do, and _also_ output
+install information in JSON format:
+```
+$ npm audit fix --dry-run --json
+```
+
+Scan your project for vulnerabilities and just show the details, without fixing
+anything:
+```
+$ npm audit
+```
+
+Get the detailed audit report in JSON format:
+```
+$ npm audit --json
+```
+
+## DESCRIPTION
 
 The audit command submits a description of the dependencies configured in
 your project to your default registry and asks for a report of known
-vulnerabilities.  The report returned includes instructions on how to act on
+vulnerabilities. The report returned includes instructions on how to act on
 this information.
 
+You can also have npm automatically fix the vulnerabilities by running `npm
+audit fix`. Note that some vulnerabilities cannot be fixed automatically and
+will require manual intervention or review. Also note that since `npm audit fix`
+runs a full-fledged `npm install` under the hood, all configs that apply to the
+installer will also apply to `npm install` -- so things like `npm audit fix
+--package-lock-only` will work as expected.
+
 ## CONTENT SUBMITTED
 
 * npm_version
@@ -29,7 +79,7 @@ the following dependency types:
 
 * Any module referencing a scope that is configured for a non-default
   registry has its name scrubbed.  (That is, a scope you did a `npm login --scope=@ourscope` for.)
-* All git dependencies have their names and specifiers scrubbed. 
+* All git dependencies have their names and specifiers scrubbed.
 * All remote tarball dependencies have their names and specifiers scrubbed.
 * All local directory and tarball dependencies have their names and specifiers scrubbed.
 
@@ -40,4 +90,5 @@ different between runs.
 ## SEE ALSO
 
 * npm-install(1)
+* package-locks(5)
 * config(7)