docs: npm access

2 files changed, 72 insertions, 2 deletions

diff --git a/doc/cli/npm-access.md b/doc/cli/npm-access.md
new file mode 100644
index 000000000..85db7e654
--- /dev/null
+++ b/doc/cli/npm-access.md
@@ -0,0 +1,63 @@
+npm-access(1) -- Set access level on published packages
+=======================================================
+
+## SYNOPSIS
+
+    npm access public [<package>]
+    npm access restricted [<package>]
+
+    npm access add <read-only|read-write> <entity> [<package>]
+    npm access rm <entity> [<package>]
+
+    npm access ls [<package>]
+    npm access edit [<package>]
+
+## DESCRIPTION
+
+Used to set access controls on private packages.
+
+For all of the subcommands, `npm access` will perform actions on the packages
+in the current working directory if no package name is passed to the
+subcommand.
+
+* public / restricted:
+  Set a package to be either publicly accessible or restricted.
+
+* add / rm:
+  Add or remove the ability of users and teams to have read-only or read-write
+  access to a package.
+
+* ls:
+  Show all of the access privileges for a package. Will only show permissions
+  for packages to which you have at least read access.
+
+* edit:
+  Set the access privileges for a package at once using `$EDITOR`.
+
+## DETAILS
+
+`npm access` always operates directly on the current registry, configurable
+from the command line using `--registry=<registry url>`.
+
+Unscoped packages are *always public*.
+
+Scoped packages *default to restricted*, but you can either publish them as
+public using `npm publish --access=public`, or set their access as public using
+`npm access public` after the initial publish.
+
+You must have privileges to set the access of a package:
+
+* You are an owner of an unscoped or scoped package.
+* You are a member of the team that owns a scope.
+* You have been given read-write privileges for a package, either as a member
+  of a team or directly as an owner.
+
+If your account is not paid, then attempts to publish scoped packages will fail
+with an HTTP 402 status code (logically enough), unless you use
+`--access=public`.
+
+## SEE ALSO
+
+* npm-publish(1)
+* npm-config(7)
+* npm-registry(7)
diff --git a/doc/cli/npm-publish.md b/doc/cli/npm-publish.md
index 30e816c7f..8c447d0df 100644
--- a/doc/cli/npm-publish.md
+++ b/doc/cli/npm-publish.md
@@ -4,8 +4,8 @@ npm-publish(1) -- Publish a package
 
 ## SYNOPSIS
 
-    npm publish <tarball> [--tag <tag>]
-    npm publish <folder> [--tag <tag>]
+    npm publish <tarball> [--tag <tag>] [--access <public|restricted>]
+    npm publish <folder> [--tag <tag>] [--access <public|restricted>]
 
 ## DESCRIPTION
 
@@ -29,6 +29,12 @@ specifying a different default registry or using a `npm-scope(7)` in the name
   <name>@<tag>` will install this version.  By default, `npm publish` updates
   and `npm install` installs the `latest` tag.
 
+* `[--access <public|restricted>]`
+  Tells the registry whether this package should be published as public or
+  restricted. Only applies to scoped packages, which default to `restricted`.
+  If you don't have a paid account, you must publish with `--access public`
+  to publish scoped packages.
+
 Fails if the package name and version combination already exists in
 the specified registry.
 
@@ -39,6 +45,7 @@ it is removed with npm-unpublish(1).
 ## SEE ALSO
 
 * npm-registry(7)
+* npm-scope(7)
 * npm-adduser(1)
 * npm-owner(1)
 * npm-deprecate(1)