WordPress Command Line Fun

Many of you may have already met the WordPress Command Line tool called wp-cli by @scribu, the man who eats WordPress for breakfast, but my first encounter with the tool happened a couple of days ago. I don’t know how in the world I had missed its announcement 4 months ago.

About the tool

The WordPress Command Line tool provides a command line interface for administrative control and management, and even installation of WordPress. The tool is written in PHP and makes use of the highly flexible and powerful PHP Command Line tools library. It requires PHP CLI SAPI to be installed on the machine, which will almost always be available if you’re running WordPress on the server.

wp-cli has to be run (using the bin/wp wrapper) from inside a WordPress root directory (if not present you can have wp-cli automatically download it) and performs the following core functions without needing to login and wait for any page loads (not all are listed here, use help to get more information:

wp core config – change/switch datagbase parameters
wp core update – update WordPress
wp db dump – dump database
wp db cli – enter mysql command line interface without entering passwords
wp db query – run a database query
wp eval – execute any PHP code after bootstrapping WordPress
wp generate posts/users – generates posts and users, there will be no warning and no undo, so make sure you don’t run it on your production site
wp option get/add/update/delete – excellent time-saving feature that interfaces with the Options API
wp plugin list, install, toggle, update – quickest ever way to manage plugins, save lots of time
wp theme – same as above
wp user – almost same as above

Apart from core commands, community commands also exist. The latest version of wp-cli has commands for Google Sitemap Generator, W3 Total Cache, and WP Super Cache.

How it works

The code behind wp-cli is elegantly simple. A WordPress wp-admin environment is loaded up by including the required bootstrap files. No logging in is required, since the front-end is not touched, only function definitions become available. The user is not logged in, anything that checks for permissions in WordPress will fail, since no current user is instantiated.

Commands are parsed from inside the commands directory. wp-cli commands can wrap around all the standard WordPress APIs and functions to accomplish different tasks, as well as any other PHP functions that interact with WordPress and the shell (to spawn MySQL, for example).

Extending

Commands can and are encouraged to be written for wp-cli. Plugins provide all sorts of functions that can be called after having successfully been loaded up. Here’s a quick example of an wp-cli command for the Hello Dolly plugin.

The hello_dolly_get_lyric() function defined inside the plugin returns a random string from Louis Armstrong’s “Hello, Dolly”.

if( class_exists( 'HelloDolly' ) ) {
  WP_CLI::addCommand( 'hello', 'HelloDolly' );
}

/* Print out a "Hello Dolly" quote */
class HelloDolly extends WP_CLI_Command {

  function __construct( $args = array(), $vars = array() ) {
    WP_CLI::line( hello_dolly_get_lyric() );
    parent::__construct( $args, $assoc_args );
  }

  public static function help() {
    WP_CLI::line( 'usage: wp hello' );
  }
}

Wrap the code into <?php tags and save the file into /src/commands/community/

~/www/wp$ php /tmp/wp-cli/src/php/wp-cli/wp-cli.php help hello
usage: wp hello
~www/wp.com$ php /tmp/wp-cli/src/php/wp-cli/wp-cli.php hello
Find her an empty lap, fellas

Easy. Note that I’ve not installed/built wp-cli as the instructions state. If you follow the instructions you would be able to simply call wp hello. Don’t forget to have the Hello Dolly plugin activated. As a matter of fact, use the tool like so wp plugin status and wp plugin activate hello. Should not take you more than 5 seconds.

A command extends the WP_CLI_Command class. A standalone command is implemented as a class constructor, subcommands are implemented as public class methods. The help message is static. The architecture is very simple.

Feel free to develop commands for your favorite plugins and issue pull requests on wp-cli github, if they are good and useful they will be included with the tool.

Conclusion

wp-cli is very powerful, probably aimed at advanced users and has to be used responsibly. Some commands (like generate) can have consequences that cannot be simply undone, there is no undo in the command line. You should definitely try out wp-cli, if you regularly manage your site and would like to see how much time you can save.

wp-cli is very young and has a lot more functionality that has yet to be implemented and fruitfully enjoyed, like comment management, maintenance mode in one command, etc. Well done, @scribu, will probably be submitting some commands over his way as soon as I code some for plugins I use.

wpshell

WordPress has a tool called wpshell, which opens an interactive PHP session instead of one-time commands that spawn WordPress every time. It has its advantages and disadvantages and will probably (and hopefully) influence how some of wp-cli features turn out.

What do you think of wp-cli? Is command line management faster than regular Dashboard browser-based management of WordPress?

Published 14 years ago by soulseekah with no comments tagged cli, plugin, review, shell in WordPress

Code, sweet, code!