Using wp-cli for Fun and Profit

See how you can perform common WordPress tasks faster or even automate them by using the power of bash.

What Is wp-cli?

wp-cli is a tool for controlling WordPress through a console window.

When the WordPress admin interface is so beautiful and easy to use, the natural question is: why would you ever use a command-line interface?

There are two main reasons:

• The keyboard is faster than the mouse – For power users, typing a command can be orders of magnitude faster than pressing a button in a web browser.
• Scripting – You can put several commands in a text file and have it executed automatically.

In this tutorial I’m going to give you a taste of what wp-cli is good for.

Installing wp-cli

Before using it, you’ll need a few things:

1. UNIX-like shell – If you’re on a Mac or on Linux, you can run wp-cli on your local machine. If you’re on Windows, you can log into your Linux server via Putty and install wp-cli there.

2. PHP 5.3+ and the php-cli utility – You can see if you have these by running the following command:

   php -v

3. Git – This is what we’ll use to install and update wp-cli.

The wp-cli project is still in it’s infancy, so the best way to stay on top of recent versions is by cloning it from github:

git clone --recurse-submodules git://github.com/andreascreten/wp-cli.git ~/git/wp-cli
cd ~/git/wp-cli
sudo utils/build-dev

~/git/wp-cli is the directory where wp-cli will be installed. Feel free to change it to whatever you want.

That’s it. Now the wp command should be available:

cd /var/www/public_html/wordpress
wp

On Multisite

If you want to use wp-cli on a multisite install, you’ll have to decide which blog you want to operate on:

wp --blog=myblog.mynetwork.com

To avoid having to pass the --blog parameter for each command, you can store it in a specially-named file:

echo 'myblog.mynetwork.com' > wp-cli-blog

wp-cli will read that file if there’s no --blog parameter.

Handling Core

First, let’s see what version of WordPress we’re dealing with:

wp core version --extra

To perform an update, you just need to write:

wp core update

Handling Plugins

Let’s see what plugins we have installed:

wp plugin status

Huh, it seems there’s an update available for Akismet. Let’s install it:

wp plugin update akismet

Now let’s install and activate a plugin from wordpress.org:

wp plugin install google-sitemap-generator --activate

Also, you can install the development version of a plugin:

wp plugin install google-sitemap-generator --activate --dev

Oh, and look, there’s a new command available now:

wp google-sitemap

We can quickly switch a plugin from active to inactive and vice-versa:

wp plugin toggle google-sitemap-generator

This is a good way to debug activation hooks.

Similarly, you can run a plugin’s uninstall procedure without deleting the plugin files:

wp plugin uninstall google-sitemap-generator

And, of course, you can delete the plugin as well:

wp plugin delete google-sitemap-generator

Handling Themes

We have a few commands for working with themes too:

wp theme status

Unlike plugins, you can only have a single theme running at a time, so activating a theme will automatically “deactivate” the previous one:

wp theme activate twentyten

And here’s a little trick to go into the directory of a particular theme:

cd $(wp theme path twentyeleven)

Generating Data

If you’re writing a theme and you want to style the pagination, you’re going to need a lot of posts. Here’s the quickest way to get them:

wp generate posts --count=1000

If you want to style a list of users, you can generate some of them too:

wp generate users --role=author

You can also create individual users:

wp user create stan stan@company.com

Creating Export Files

You might want to periodically export your content to a WXR file.

wp export --path=./ --user=admin

You can pass additional parameters to limit what content is exported, such as --category, --start_date etc.

Changing Options on the Fly

There are straightforward commands for CRUD operations on options:

wp option get permalink_structure
wp option add foo bar
wp option delete foo

You don’t want to do this on a regular basis, as most options are constrained to certain values. But it can come in handy in scripts.

Database Operations

If you want to make a backup of the database, just write:

wp db dump

Or perhaps you need to do a quick query to find when the last post was published:

wp db query "SELECT MAX(post_date) from wp_posts WHERE post_type = 'post' AND post_status = 'publish'"

Opening an interactive MySQL session to do some diagnostics is just as easy:

wp db cli

Running Arbitrary Code

Sometimes, the only way to tell wp-cli what you want is by describing it in PHP code:

wp eval-file do-my-laundry.php

With the above command, wp-cli will first load WordPress and then load and execute your PHP file.

This is useful in deploy scripts or for other complex actions that can’t be achieved using built-in commands.

You can also pass PHP code inline:

wp eval 'echo WP_CONTENT_DIR;'

Creating Your Own Commands

Believe it or not, wp-cli is written mostly in PHP. Each command is a class, with each method representing a subcommand.

The neat thing is that you can make your own class, put it in a plugin and wp-cli will automatically recognize it as one of it’s own. A detailed tutorial for creating commands is available in the project wiki.

Conclusion

I hope I’ve convinced you to at least give wp-cli a try. If you’ve found a bug or if you have a feature request, consider opening an issue.

Have an interesting use case for wp-cli? Please share it in the comments below.