diff --git a/README.md b/README.md
index 413047c5..5f70a36f 100644
--- a/README.md
+++ b/README.md
@@ -200,11 +200,17 @@ wp package install <name|git|path|zip> [--insecure] [--interaction]
 Packages are required to be a valid Composer package, and can be
 specified as:
 
-* Package name from WP-CLI's package index.
+* Package name, such as `wp-cli/server-command`.
 * Git URL accessible by the current shell user.
 * Path to a directory on the local machine.
 * Local or remote .zip file.
 
+A package name is looked up in WP-CLI's package index, which is deprecated,
+and then on Packagist. If neither has it, WP-CLI tries
+`https://github.com/<package-name>.git` and then
+`https://gitlab.com/<package-name>.git`. Set the `GITHUB_TOKEN` or
+`GITLAB_TOKEN` environment variable to avoid rate limiting on that check.
+
 Packages are installed to `~/.wp-cli/packages/` by default. Use the
 `WP_CLI_PACKAGES_DIR` environment variable to provide a custom path.
 
diff --git a/src/Package_Command.php b/src/Package_Command.php
index 41c2fd62..d4642647 100644
--- a/src/Package_Command.php
+++ b/src/Package_Command.php
@@ -169,11 +169,17 @@ public function browse( $_, $assoc_args ) {
 	 * Packages are required to be a valid Composer package, and can be
 	 * specified as:
 	 *
-	 * * Package name from WP-CLI's package index.
+	 * * Package name, such as `wp-cli/server-command`.
 	 * * Git URL accessible by the current shell user.
 	 * * Path to a directory on the local machine.
 	 * * Local or remote .zip file.
 	 *
+	 * A package name is looked up in WP-CLI's package index, which is deprecated,
+	 * and then on Packagist. If neither has it, WP-CLI tries
+	 * `https://github.com/<package-name>.git` and then
+	 * `https://gitlab.com/<package-name>.git`. Set the `GITHUB_TOKEN` or
+	 * `GITLAB_TOKEN` environment variable to avoid rate limiting on that check.
+	 *
 	 * Packages are installed to `~/.wp-cli/packages/` by default. Use the
 	 * `WP_CLI_PACKAGES_DIR` environment variable to provide a custom path.
 	 *