If you’ve been to a WordCamp or two, chances are good that you’ve heard of the existence of a thing called “WP CLI.” Maybe that’s all you know. Maybe you’ve used it. Maybe you have a sinking feeling of guilt when you hear that name because you feel like you should have used it by now. Whatever the case, this article will tell you what WP-CLI is, how you get it, and why you might want to.
Around this and all other learning, don’t forget the two rules: no blame and no shame. You learn what you need when you need it, if you don’t know something you shouldn’t feel embarrassed to ask. People who don’t honor learning are jerks.
What WP-CLI Is (and Isn’t)
For those who’ve never heard of it, understanding WP-CLI starts by understanding what the letters mean. They stand for “WordPress Command Line Interface”. That means that WP-CLI is a program that allows you to use WordPress on the command line. Don’t know what the command line is? We’ve got an article explain exactly what a “terminal” is why they’re useful. The executive summary is that it’s a low-interface way to manipulate WordPress.
The next obvious question, if we understand the idea of using WordPress from the command line is “Why?” The basic reasons are as follows, in no particular order:
- It’s faster. A keyboard-only interface is faster for experienced users than a mouse-and-keyboard graphical interface can be.
- It’s automatable. As GUI-less commands are faster for experienced humans, they’re WAY easier for machines. That’s one of the big places where WP-CLI shines. It’ll take care of hundreds of installs in a jiffy if you’re good at shell scripting.
- It’s got weird powers. There aren’t a ton of things, but WP-CLI has some pretty neat and useful tricks. We’ll detail a few in this article. Things that WordPress itself can’t do WP-CLI can and does sometimes do for you.
Those reasons listed, there are also reasons not to use WP-CLI. Primarily: you don’t need it and it’s not helping you with things you care about. If you have a single WordPress site on a single server, there’s no need to think about WP-CLI. If you don’t know how to use the command line, don’t think or worry about WP-CLI. (But if you’re interested, here are the basics of file and non-file Unix CLI commands.) WP-CLI isn’t essential and it’s not something you should ever feel bad about. It’s a useful tool that can help you out a lot, but only if you have the specific problems that it solves well.
How to Install WP-CLI
The process of installing WP-CLI is only a few steps. And the official WP-CLI site lays them out quickly and cleanly. There’s really only one reason that you may need more than following those directions. That you need or want to know what each command you’re typing into your terminal is doing. If you’re looking for that check out our latest Quick Guide: Installing WP-CLI. Here’s its video:
Cool Tricks You Can Do With WP-CLI
This isn’t an exhaustive WP-CLI tutorial. There are two reasons for that: first, such a thing is pretty silly. If you understand how to run one CLI command, explaining each in detail is a waste. The other reasons is that we’ve not got time or space to really do that. The WP CLI can do so many things for you, and a lot of them aren’t used that much. So we’ll instead cover the seven uses of WP-CLI that are worth knowing about. These are things that I find WP-CLI does better than most other solutions I know of, and that I’ve used and loved before.
Quickly Update all Core Files
Keeping WordPress up-to-date is one of the easiest things you can do to keep it secure. It’s increasingly easy, but you can do it with WP-CLI too.
It’s as simple as:
wp core update
That’s great. But WP-CLI can do more. Let’s suppose that WordPress is up-to-date, but you worry that someone has tampered with the core files in your WordPress site. Maybe you think you were hacked, maybe you think you work with a dummy. Either way, you can use a similar command to put WordPress core back to a known-good state. Just run:
wp core download --force
With that, even if you don’t need an update, you’ll get your WordPress core files replaced with freshly downloaded ones from WordPress.org. Other solutions exist—you can download a zip, extract it, then upload those files—but they’re not even a third as fast. You could probably do the whole WP-CLI install and run the command in less time than the manual FTP solution would take.
There are a few other useful but subtly different commands. The clearest of these is wp core verify-checksums
. This is a great little command, because it’ll just tell you immediately if the WordPress core files you have on your site have been tampered with. It also tells you if there are unexpected files in the WordPress installation. But unlike the wp core download
command, it doesn’t change them. This is great because it means that you can easily handle the case of wanting to do a forensic investigation if any core files have changed.
Update a Plugin or Theme from the Command Line
You can use WP-CLI to install a singe plugin. I do this often for new sites with a few plugins I use a lot. It looks like:
wp plugin install plugin-slug
Add the --activate
flag to install and activate the plugin in one stroke. If you want to activate an already-installed plugin, you can do that too with a simple wp plugin activate plugin-slug
.
Update all Plugins or Themes with WP-CLI
If you have confidence in the ability to safely update the plugins and themes on your site, you can simply issue two commands to get your site up-to-date:
wp plugin update --all
wp theme update --all
Which command updates plugins vs themes is so straight-forward from the command’s text that I won’t do us the unnecessary chore of detailing it. I will just say that these are some of favorite things. They were great before we had the newer update features in the WordPress dashboard, and they’re still great now. (Though I enjoy dashboard updates a lot more now.)
WP-CLI Can Dump the WordPress Database
To “export” the database is to take the data from your WordPress MySQL database and write it out to a single flat text file. That’s useful for both backup/snapshot reasons, and for the sake of being able to move a site. Of the latter more below. You do it like this:
wp db export [<file>]
This command has an optional argument of the file name. If you don’t specify one, it’ll default to the name of your database. If you specify it, it’ll write the file out to the file you name.
For data-security reasons, a real backup solution is more than doing local dumps of database files onto the server your WordPress site is running on. But this simple command is a great first step.
Easily Import into the WordPress Database using WP-CLI
As you may have guessed, an “import” is taking a flat file of database information and writing it into the live WordPress database. That way, the “imported” data starts to affect what the site looks and feels like. This is useful if you’ve done an export for data migration reasons:
wp db import [<file>]
If you’re conversant in databases, you know that a data migration in WordPress is basically a three step process: an export, an import, and a find-and-replace. Which means that we’ve covered two of the three steps. The last remaining one is…
Find-and-replace in the WordPress database with WP-CLI
wp search-replace <old> <new>
So if we moved out site from “wpshout.com” to “wpisgreat.org”, we’d do:
wp search-replace wpshout.com wpisgreat.org
With the export, the import, and then the replace command our site would be back up in running at the new URL in seconds. You may need to use rsync
or a similar command to push the exported file to the server it should be imported on. See our recent article about how that command works if you’re looking to do that.
Using WP-CLI to Regenerate Thumbnails
One the most common tasks a WordPress developer need to do when redesigning a WordPress site is regenerate the images for the new featured image size on their new theme. This doesn’t always happen, but it does a lot in my experience. If you don’t know the command line, you probably use the great little Regenerate Thumbnails plugin for this. You can easily accomplish this with WP-CLI though. All you need is the little command:
wp media regenerate
This will do exactly what the plugin does for you. It give you less useful output, but in my experience it also accomplishes the task a good deal faster. The command also has some interesting and useful options:
<attachment-id>
— If you have one specific image that you’re having issues with, you can constrain the command to working on that ID, or IDs.--skip-delete
— This option stops the command from deleting images of different sizes that may no longer be registered on the site. For most WordPress sites it’s unnecessary, but if you want old hotlinks to your images to still work, you may want to include this argument.--only-missing
— This option making the command only generate thumbnails of sizes that are missing. This especially useful on large sites where you’re just needing to get a new size of image.
We’re Just Scratching the Surface of WP’s CLI
With WP-CLI, you can manage transients and the object cache, run single PHP files after you’ve loaded WordPress, quickly scaffold out a testing infrastructure, and a whole lot more. This is list is just the things that came to mind that I use regularly when administering and developing WordPress sites.
In all cases, --help
is a great place to start. wp --help
gives you a listing of all the things that the wp command can do. And if you’re interested in specific subset of features, wp plugin --help
or similar gives you a deeper dive on that little set of features. Getting comfortable using your terminal to read those documents is a good idea.
Why You Need WP-CLI in Your Life
WP-CLI is just a great tool for people who need to do small little administrations tasks on a WordPress site on a regular basis. It has powers far beyond what we’ve seen. But quickly bringing a WordPress site up-to-date in a few CLI commands is so much faster than going through the interface that most developers quickly learn to love WP-CLI. It’s not the cure-all for your WordPress problems, but it helps with so many tasks a developer need to do on a site that it’s essential to be familiar with it.
[…] The What, How and Why of WP-CLI: WordPress in Your Terminal […]
[…] The What, How and Why of WP-CLI: WordPress in Your Terminal […]
Search and Replace is definitely one of the most valuable uses of WP-CLI available, in my opinion. In addition to Matt’s comment about using the –dry-run flag, my other favourite is the –export option, which allows you to do a search and replace, but instead of making the changes to the database, it creates a SQL file with changes made there. So, you’re in your dev environment, but need to prepare a copy of the database for production?
wp search-replace mydevdomain.local productionexample.com –export=production.sql
Boom! You have a file ready to import into your production environment, but your database in development still works!
Learning what WP-CLI can do for me has been on my to-do list for a long time–this article was a step in the right direction. Thanks very much for it.
I’m actually interested in potentially using WP-CLI for automation–specifically WordPress installs. Do you have a tutorial or description you could maybe recommend that might get me started?
Quick note on using search-replace: I always us the –dry-run flag before running a live search replace. It helps to provide a first level sanity check and many times has prevented some tragic misspellings. Should certainly be built into the workflow to make sure the results match your expectations.