Command-Line WordPress – WordCamp Philly 2012

This presentation, by Ben Doherty, was a bit of a surprise. The title given in the schedule referred to ‘wp-cli’ and I really didn’t know what that was, but stayed in the “Developer Track” room anyway. This is basically an implementation of WordPress entirely on the command line, which allows doing a lot of cool things very quickly and easily, and can even be included in shell scripts to perform these tasks automatically.

It’s a little difficult at first to understand how anything in WordPress that can be done graphically could be done via command line, until one realizes that all the buttons, sliders and options do is execute some PHP code, so basically that PHP code can be triggered by text commands instead.

This presentation got very code heavy very fast, but the entire presentation can be found at It deserves probably several viewings…

Command Line WordPress starts with a wrapper around PHP called WPShell or wpsh. (This is the command interpreter that changes your commands into whatever would have happened if you clicked a button or manipulated another graphical control.)

WPShell is written in Python, so that’s of course a requirement on the server you’re running (Python support). WPShell, like bash, sh and lots of other shells, has command completion using the tab key.

One must create a wpsh launcher to setup the WordPress environment. Look for some examples on how to initialize wpsh on github (search for ‘Ben Doherty’ or ‘WPShell’). Once this is done, put the shell script somewhere, and run it to start the interpreter.

WPShell uses ctags to index possible commands and can use command completion (with the tab key) to get a list of functions. Output from a function would then often appear as an array of variables. This could be used to easily see how variables are actually set at various times, depending on the actions that have just occurred. One can also use wpsh to look at the PHPDoc entry for a specific function. (PHPDoc is an automated method for creating documentation, whereby comments in the code are tagged in a certain way to mark them as documentation, which can be easily searched later. Linux/Unix users will be familiar with a similar tool, using the ‘man’ command to get the manual page for a specific command or keyword.)

Extra functions can be put into a wprc file to store those functions that need only exist when using the wpsh environment.

Putting this together with wpcli:

wpcli uses “proper” CLI design– if a command does not specify any arguments, but requires arguments be specified, the interface will show a description of the arguments, maybe with help for additional details. Make sure to put lots of echo statemtns in your scripts, so you can see what warnings and feedback is generated from the interface.

The stock commands included with wpsh allow for scripted upgrade, status, etc. of themes, plugins and more, potentially across sites and domains.

For those who want to extend wpcli to have more commands, functions, etc., the interface tries to make this easy by offering hints, and attempts to automate much of the process of creating new commands. Each new command “extends” another parent command. When creating scripts, make them very verbose, so it’s obvious what’s going on in the script to anyone who reads it (including yourself, months down the road).

wpcli can be a handy tool in getting around restrictions placed on the graphical version, such as the export limitations: memsize, no-scriptable, etc. It can also be used to bulk import data into a site, and can remap authors and URLs.

Unfortunately, WordPress is not optimized for a command-line interface: it expects a command->response->die lifecycle, but most functions will work in this new interface nonetheless.

Related Posts: