Making a WP-CLI Plugin

I love wp-cli. It makes my life so much easier in so many ways.

I’ve added in some basic commands to some of my plugins because it makes things easier for others. And as it happens, adding wp-cli commands to your plugins isn’t actually all that hard. But did you know you don’t have to?

The Basic Code

For our example I’m going to make a command called halfelf and it’s going to have a sub-command called ‘stats’ which outputs that the HalfElf is alive. And that looks like this:

WP_CLI::add_command( 'halfelf', 'HalfElf_CLI' );

class HalfElf_CLI extends WP_CLI_Command {

	/**
	 * Get HalfElf Stats
	 *
	 * ## EXAMPLES
	 *
	 * wp halfelf stats
	 *
	 */
	public function stats( ) {
		WP_CLI::success( __( 'HalfElf is currently alive.', 'halfelf' ) );
        }
}

The docblock controls the output for the help screen, which is possibly the most brilliant thing about it.

Of course, all that does is make a command that doesn’t rely on any WordPress plugin, which is cool. Here’s a different example. In this one, I’m triggering a command to my logger function to reset the backup log or to view it:

	/**
	 * See Log Output
	 *
	 * ## OPTIONS
	 *
	 * empty: Leave it empty to output the log
	 * 
	 * reset: Reset the log
	 *
	 * wp dreamobjects logs
	 * wp dreamobjects logs reset
	 *
	 */

	public function log( $args, $assoc_args  ) {
		if ( isset( $args[0] ) && 'reset' !== $args[0] ) {
			WP_CLI::error( sprintf( __( '%s is not a valid command.', 'dreamobjects' ), $args[0] ) );
		} elseif ( 'reset' == $args[0] ) {
			DHDO::logger('reset');
			WP_CLI::success( 'Backup log reset' );
		} else {
			file_get_contents( './log.txt' );
		}
	}

Because wp-cli runs as WordPress, it has access to WordPress commands and functions.

But. Where do we put this file?

In a WordPress Plugin

If you want to use that code in a WordPress plugin, you put it in a file called wp-cli.php (or whatever you want) and then call it in your main WordPress plugin file like this:

if ( defined( 'WP_CLI' ) && WP_CLI ) {
	require_once( 'wp-cli.php' );
}

If you do that, I would recommend putting this at the top of your wp-cli.php file.

if (!defined('ABSPATH')) {
    die();
}

// Bail if WP-CLI is not present
if ( !defined( 'WP_CLI' ) ) return;

That will prevent people from calling the file directly or in other ways.

In the case of my DHDO code, I added in this check:

if( class_exists( 'DHDO' ) ) {
	WP_CLI::add_command( 'dreamobjects', 'DreamObjects_Command' );
}

That means if (for whatever reason) DHDO can’t be found, it prevents you from doing things.

On It’s Own

But. That first command doesn’t need a plugin, does it? So if it doesn’t need a plugin, could I still use them? The answer is of course. The wp-cli.php file is the same, but where you put it changes. This will all be done in SSH. You could do it in SFTP if you wanted.

In your home (or root) directory we have to make a folder called .wp-cli – please note the period, it’s like your .htaccess file. Except it’s a folder. In there you’re going to make a folder called commands and in that folder we’ll put another one for our commands. Like if I’m putting my HalfElf commands out there, I’d make a folder called halfelf and in there I put my command file command.php

That gives me this: ~/.wp-cli/commands/halfelf/command.php

However that doesn’t act like plugins or themes or mu-plugins, you have to add the command to another file. I know, I know. Make a file called config.yml and put it in .wp-cli so you have this: ~/.wp-cli/config.yml

The content of that file is this:

require:
  - commands/halfelf/command.php
  - commands/some-other/command.php

And that’s it! Now you’ve got some command line tools for your WordPress site!

Ipstenu (Mika Epstein)

I’m Mika (aka Ipstenu) and I’m complicated. I’ve been on the net since the days of dedicated terminals and Novation CAT modems and solved Missionaries and Cannibals (or Goats and Cabbages) before I was six, and blog about WordPress and technical/computer things at Half Elf on Tech.

See Full Bio