From 918bb8a92f847a61e71aabad420b52cc6196d52e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 17 Mar 2026 16:34:44 +0000
Subject: [PATCH 1/2] Initial plan


From a7c5179dc8c25004f27519541a844e31de4a4f70 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 17 Mar 2026 16:43:19 +0000
Subject: [PATCH 2/2] Add documentation on where to add WP-CLI customizations
 globally

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
---
 guides/commands-cookbook.md                   | 27 ++++++++++++++++++-
 references/internal-api/wp-cli-add-command.md |  2 ++
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/guides/commands-cookbook.md b/guides/commands-cookbook.md
index 1945bb1a..9eb93ce6 100644
--- a/guides/commands-cookbook.md
+++ b/guides/commands-cookbook.md
@@ -490,9 +490,34 @@ Functional tests typically follow this pattern:
 
 Convinced? Head on over to [wp-cli/scaffold-package-command](https://github.com/wp-cli/scaffold-package-command) to get started.
 
+## Adding commands globally
+
+If you want to have custom commands available globally, without needing to create a full plugin or package, you can use WP-CLI's `require` configuration option.
+
+Edit your [global config file](https://make.wordpress.org/cli/handbook/references/config/) (usually found at `~/.wp-cli/config.yml`) to require a PHP file:
+
+```yaml
+require:
+  - ~/.wp-cli/commands.php
+```
+
+Then create the file and add your custom commands:
+
+```php
+<?php
+
+WP_CLI::add_command( 'hello-world', function () {
+    WP_CLI::success( "Hello World!" );
+} );
+```
+
+Any commands registered in that file will be globally available whenever you run WP-CLI. This is great for personal helper commands that you want available across all your WordPress projects.
+
+You can also pass the `--require=<path>` flag on the command line, or set the `WP_CLI_REQUIRE` environment variable, to load a custom PHP file for a single invocation.
+
 ## Distribution
 
-Now that you've produce a command you're proud of, it's time to share it with the world. There are two common ways of doing so.
+Now that you've produced a command you're proud of, it's time to share it with the world. There are two common ways of doing so.
 
 ### Include in a plugin or theme
 
diff --git a/references/internal-api/wp-cli-add-command.md b/references/internal-api/wp-cli-add-command.md
index 35bfd0cd..dd96aaff 100644
--- a/references/internal-api/wp-cli-add-command.md
+++ b/references/internal-api/wp-cli-add-command.md
@@ -51,6 +51,8 @@ WP_CLI::add_command( 'foo', $foo );
 ```
 
 
+For guidance on where to place your custom commands (e.g. globally via `~/.wp-cli/config.yml`, in a plugin or theme, or as a standalone package), see the [Commands Cookbook](https://make.wordpress.org/cli/handbook/guides/commands-cookbook/).
+
 *Internal API documentation is generated from the WP-CLI codebase on every release. To suggest improvements, please submit a pull request.*