How to Create Your Own WP-CLI Command: A Beginner-Friendly Guide

Introduction

WP-CLI (WordPress Command Line Interface) is a powerful tool that allows developers and administrators to manage WordPress websites directly from the command line. While WP-CLI comes with a wide range of built-in commands, there are times when you may need to create your own custom commands to handle specific tasks.

In this guide, we’ll walk you through the process of creating your own WP-CLI command, from setting up the environment to writing and testing your custom code. Whether you’re a beginner or an experienced developer, this tutorial will help you streamline your WordPress workflows.

What is WP-CLI?

WP-CLI is an open-source command-line tool for managing WordPress installations. It allows you to perform tasks like updating plugins, managing users, exporting databases, and much more—all without needing to log into the WordPress admin dashboard.

Creating custom WP-CLI commands can help you automate repetitive tasks, integrate with third-party tools, or extend WordPress functionality in ways that suit your specific needs.

Prerequisites

Before you start creating your custom WP-CLI command, ensure you have the following:

A WordPress installation: You’ll need access to a WordPress site where you can test your custom command.
WP-CLI installed: If you don’t already have WP-CLI installed, follow the official installation guide.
Basic PHP knowledge: Since WP-CLI commands are written in PHP, familiarity with the language is essential.
A code editor: Use any editor of your choice, such as VS Code, Sublime Text, or PHPStorm.

Step-by-Step Guide to Creating a Custom WP-CLI Command

Step 1: Create a Custom Plugin

The easiest way to add a custom WP-CLI command is by creating a WordPress plugin. Start by creating a new folder in the wp-content/plugins directory of your WordPress installation. For example, name it custom-wpcli-command.

Inside this folder, create a PHP file named custom-wpcli-command.php and add the following boilerplate code:

<?php
/**
 * Plugin Name: Custom WP-CLI Command
 * Description: A plugin to add custom WP-CLI commands.
 * Version: 1.0
 * Author: Your Name
 */

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

Activate the plugin from the WordPress admin dashboard or via WP-CLI using:

wp plugin activate custom-wpcli-command

Step 2: Register Your Custom Command

To register a custom WP-CLI command, use the WP_CLI::add_command() function. Add the following code to your plugin file:

if ( defined( 'WP_CLI' ) && WP_CLI ) {
    WP_CLI::add_command( 'custom_command', 'Custom_Command' );
}

Here, custom_command is the name of your command, and Custom_Command is the class that will handle the command’s functionality.

Step 3: Define the Command Class

Next, define the Custom_Command class and add the logic for your command. For example, let’s create a simple command that outputs a greeting message:

class Custom_Command {
    /**
     * Outputs a greeting message.
     *
     * ## OPTIONS
     *
     * <name>
     * : The name of the person to greet.
     *
     * ## EXAMPLES
     *
     *     wp custom_command greet John
     *
     * @when after_wp_load
     */
    public function greet( $args, $assoc_args ) {
        list( $name ) = $args;
        WP_CLI::success( "Hello, $name! Welcome to WP-CLI." );
    }
}

In this example:

The greet method is the subcommand.
The <name> parameter is a required argument.
The @when after_wp_load annotation ensures the command runs after WordPress is fully loaded.

Step 4: Test Your Command

Save your changes and test the command in your terminal. Run the following:

wp custom_command greet Maxx

You should see the output:

Success: Hello, Maxx! Welcome to WP-CLI.

Step 5: Add More Functionality

You can extend your custom command by adding more methods or handling additional arguments and options. For example, let’s add a subcommand to list all published posts:

class Custom_Command {
    // Greet subcommand
    public function greet( $args, $assoc_args ) {
        list( $name ) = $args;
        WP_CLI::success( "Hello, $name! Welcome to WP-CLI." );
    }

    // List posts subcommand
    public function list_posts( $args, $assoc_args ) {
        $posts = get_posts( array( 'post_status' => 'publish' ) );

        if ( empty( $posts ) ) {
            WP_CLI::warning( 'No published posts found.' );
            return;
        }

        foreach ( $posts as $post ) {
            WP_CLI::line( "ID: {$post->ID} | Title: {$post->post_title}" );
        }
    }
}

WP_CLI::add_command( 'custom_command', 'Custom_Command' );

Now, you can run:

wp custom_command list_posts

Best Practices for Creating WP-CLI Commands

Use clear and descriptive names: Choose command and subcommand names that are easy to understand.
Document your commands: Use annotations like ## OPTIONS and ## EXAMPLES to provide helpful documentation for users.
Handle errors gracefully: Use WP_CLI::error() or WP_CLI::warning() to handle errors and provide feedback.
Test thoroughly: Test your commands in different environments to ensure compatibility and reliability.

Conclusion

Creating your own WP-CLI command is a great way to enhance your WordPress development workflow. By following this guide, you can build custom commands tailored to your specific needs, saving time and effort in managing your WordPress sites.

Start small with simple commands, and as you gain confidence, explore more advanced functionality. WP-CLI’s flexibility and power make it an indispensable tool for WordPress developers and administrators alike.

How to Create Your Own WP-CLI Command: A Step-by-Step Guide