Want a free year on Tuts+ (worth $180)? Start an InMotion Hosting plan for $3.49/mo.
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.
Before using it, you'll need a few things:
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.
PHP 5.3+ and the php-cli utility - You can see if you have these by running the following command:
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
If you want to use wp-cli on a multisite install, you'll have to decide which blog you want to operate on:
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
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
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:
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
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)
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 email@example.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
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.
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.
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.