Skip to content

Add guidance on where to place custom WP-CLI commands #631

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
swissspidy merged 2 commits into from
Mar 17, 2026
+28 −1
Merged

Add guidance on where to place custom WP-CLI commands #631

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
918bb8a
Initial plan
Copilot Mar 17, 2026
a7c5179
Add documentation on where to add WP-CLI customizations globally
Copilot Mar 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion guides/commands-cookbook.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment on lines +497 to +501
```

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

Expand Down
2 changes: 2 additions & 0 deletions references/internal-api/wp-cli-add-command.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.*


Expand Down
Loading