wp-cli-extending

WP-CLI: Extending with Custom Commands

WP-CLI is the maintenance / automation interface to a WordPress install. Almost no plugin ships CLI commands — even though wp myplugin import, wp myplugin clear-cache, wp myplugin run-sync are exactly what ops people want. The API is WP_CLI::add_command() and a class with PHPDoc-annotated methods.

When to use this skill

Trigger when ANY of the following is true:

• A plugin needs a CLI surface — bulk import / export, data migration, queue dispatch, debug introspection, scheduled-job force-run, cache clear, license activate.
• Code references WP_CLI::add_command, WP_CLI::log, WP_CLI::success, WP_CLI::warning, WP_CLI::error, WP_CLI::confirm, WP_CLI::runcommand, WP_CLI::add_hook, WP_CLI\Utils\format_items, WP_CLI\Utils\make_progress_bar, WP_CLI\Utils\get_flag_value.
• The user has a long-running admin task (update_option loop over 50k rows, AJAX-timing-out import) and wants to run it from terminal.
• Code is checking if ( defined( 'WP_CLI' ) && WP_CLI ) and the body is empty / wrong.

The bootstrap — guard, then register

// In the plugin's main file or a dedicated CLI bootstrap.
if ( defined( 'WP_CLI' ) && WP_CLI ) {
    WP_CLI::add_command( 'myplugin', MyPlugin\CLI\Commands::class );
}

The class is instantiated lazily when WP-CLI dispatches a myplugin ... invocation. PHPDoc on each method is what drives synopsis / help. Public methods become subcommands. Method names are used as-is, so import_licenses registers wp myplugin import_licenses unless you add @subcommand import-licenses. Use @subcommand for normal hyphenated command names.

Full worked example (import + list with progress bar, dry-run, format args) lives in reference.md. The skeleton:

namespace MyPlugin\CLI;

final class Commands {
    /**
     * One-line description.
     *
     * ## OPTIONS
     *
     * <file>
     * : Positional, required.
     *
     * [--dry-run]
     * : Optional flag.
     *
     * @subcommand import-licenses
     * @when after_wp_load
     */
    public function import_licenses( array $args, array $assoc_args ): void {
        [ $file ] = $args;
        $dry = (bool) \WP_CLI\Utils\get_flag_value( $assoc_args, 'dry-run', false );
        // ... work, with \WP_CLI::log() / success() / error() ...
    }
}