4elements

blog

What Is WP-CLI? A Beginner’s Guide

WP-CLI has been around for quite some time now (circa 2011) and has steadily gained momentum in the WordPress developer community. But what is it exactly, and how can you use it in your WordPress workflow?

The idea behind WP-CLI is that it allows you to interact with, and manage, WordPress sites via a command line interface. According to the official documentation, it's a command line alternative to using the traditional WordPress admin user interface.

The command line approach makes sense as you can typically do things on a computer much quicker via the command line, and the WP-CLI is no different. If you've ever used the command line on Windows, or the Terminal on macOS, then you'll be right at home using the WP-CLI.

However, this is a tutorial aimed at beginners, so don't worry if you're not a command line guru. If you've never used the WP-CLI or the command line before, then you're in good company and definitely in the right place!

Before we go any further, I've a confession to make. As I hinted above, I've never actually used the WP-CLI before! I've known about it for quite a while and have been itching to try it out, but never gotten around to actually installing it and using it. Until now, that is…

So we'll be literally in this together and working out how to use the WP-CLI both as complete beginners. I'm really interested to see how the WP-CLI fits into my existing WordPress development workflow and if it can help boost productivity.

Are you ready to get started? OK then, let's go!

Installing WP-CLI

Installing the WP-CLI for the first time can seem a bit daunting. I had to read the installation instructions a couple of times before it made sense. But, as it turns out, it isn't that difficult once you understand exactly what's required.

To start with, we need to get the latest version of WP-CLI. The recommended way to do this is to download the WP-CLI as a Phar file via the command line. This is just a PHP archive file containing all the PHP files needed for the WP-CLI to run, all wrapped up in a single convenient file ready for us to download.

To make using the WP-CLI more convenient, we want to be able to run it from anywhere and via a shorter command such as wp rather than having to type in wp-cli.phar every time.

We can do this via the following two commands:

chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp

Now try to run wp --info in a terminal window (pointing to any directory). If you see the same output as earlier when you ran php wp-cli.phar --info then you’re in business. WP-CLI is set up and ready for use!

There are other ways you can install WP-CLI, such as via Composer, so you might want to check out the alternative methods if you're struggling with the recommended default method.

Installing on Windows

Installing on Windows is slightly more involved, as PHP isn’t available from the command line by default. You can install PHP manually, but the easiest way is to use a local development server such as MAMP because PHP is automatically installed as part of the overall package.

Once PHP is available on your system you'll need to find the path to the PHP executable and make it available globally (this is covered in detail in the PHP Manual).

With PHP installed and available from any directory, download the wp-cli.phar file manually and save it to a folder such as c:\wp-cli. To be able to run the WP-CLI via the wp command just like we did on macOS, create a batch file called wp.bat inside the same folder you saved the wp-cli.phar archive file.

Add this to the batch file:

@ECHO OFF
php "c:/wp-cli/wp-cli.phar" %*

Finally, add c:\wp-cli to your global path:

setx path "%path%;c:\wp-cli"

The WP-CLI should now be available from any command line window.

An Even Easier Way!

If you’re feeling a little bit lost right now then I may have a lifeline for you. If you’re a DesktopServer user then WP-CLI is extremely easy to set up. Since DesktopServer 3.8.2, a new developer plugin is available which installs the WP-CLI on all your development sites!

Once it's activated, you can access the WP-CLI via the main DesktopServer site list, or the WordPress Toolbar.

If you do have access to DesktopServer then I'd definitely recommend installing the WP-CLI this way, as it's by far the simplest setup method. I've used DesktopServer for the last couple of years, so I'm lucky that WP-CLI installation was a breeze for me.

Using WP-CLI Remotely

This tutorial is aimed at beginners who are new to the WP-CLI, using a local WordPress installation. However, if you want to execute commands on a remote server (i.e. a live WordPress site) then you can still follow along if you have WP-CLI installed.

You'll need to be able to connect to the server via an SSH client and have your hosting account login details handy. Once connected and logged in, you'll be able to use all the WP-CLI commands in this tutorial.

It's worth contacting your host to see if they support the WP-CLI as installing it will be much simpler.

Testing the Waters

Hopefully by now you’ll have the WP-CLI installed, in which case you can relax a bit as you’ve just done the hardest part!

Open up a command line window in the root directory of the WordPress website you want to work with, which should look similar to the screenshot below.

One advantage to using DesktopServer is that it automatically opens a command window pointing to the correct root WordPress site directory. I thought that was a nice touch, especially if you're working on multiple sites.

So, to access the WP-CLI, you type wp followed by a command and/or parameter. If wp is entered, you just get a long list of available commands and parameters (which I won't show here, but try it yourself).

Our first command contained a parameter. The difference is that a parameter is preceded by two hyphens. The key to the WP-CLI is that almost all commands contain sub-commands (and parameters). This hierarchy is very well organized and is easy to understand and follow.

All commands follow a similar structure, so once you have mastered a couple of commands you'll find it easy to expand to learning more commands. The rest of this tutorial will be about learning some of the commands and parameters available in the WP-CLI.

Let's take a look at a few basic WP-CLI commands, and their output, to get a feel for how it works.

First let's get the current version of WP-CLI we're running.

wp --version

WP-CLI 1.0.0

We can run a similar command to find the current version of WordPress.

Here we have a parameter that requires one or more values to be specified. This is very common, and you'll get used to this very quickly. In this case, we listed only the fields we wanted to show (name, version).

This simply outputted all plugins again as they are all currently inactive. We'll change this shortly when we begin to enter commands to manage plugins (and themes).

You may have noticed in the commands above that there are two command words used (plugin and list). If you type in wp plugin on its own, this won't run a command but list all the sub-commands of wp plugin. Try it yourself.

So the list command is just one of multiple sub-commands available for the 'parent' plugin command. Many other commands work in a similar way.

Type in wp core and wp theme to see a list of their sub-commands too.

You can use multiple parameters on the same line too. For example, if we wanted to list plugins with updates available, and restrict outputted fields, we can combine parameters onto a single line as follows:

wp plugin list --fields=name,version --update=available

By default, you get results of a WP-CLI command outputted in table format, but this can easily be changed to JSON or comma separated value (CSV) instead by using the --format parameter.

Now that we have a handle on how to enter basic WP-CLI commands, let's see how we can do some useful WordPress admin tasks via the command line.

Plugins and Themes

The real power of the WP-CLI becomes clear when you start manipulating WordPress via the command line. In this section we'll see just how easy it is to install/delete, and activate/deactivate plugins and themes via the WP-CLI.

For plugins and themes hosted in the WordPress repository, simply enter the name after the install command as follows:

For plugins and themes hosted elsewhere, simply enter the full path to the zip file. The plugin/theme name is actually the slug, which is handy to remember if your plugin/theme name is made up of more than one word.

For example, to install the Theme Check plugin from the WordPress repository:

wp plugin install theme-check

To activate a plugin, use the activate command.

wp plugin activate jetpack

Or you can install and activate a plugin all on one line.

wp plugin install jetpack --activate

To delete a plugin, use the delete command.

wp plugin delete jetpack

Notice that you didn't have to deactivate the plugin before we deleted it, as you have to do in the WordPress admin. The install/activate/delete process is the same for themes.

Posts and Pages

There are various WP-CLI commands to manage any type of post, including a way to mass generate posts.

This creates a post with a specific title, and content. By default, posts will be created with draft status, so if we want them to be published straight away then we need to set the post_status parameter to publish.

Creating a page with content is just as easy—simply set the post_type parameter to page (this is set to post by default).

wp post create --post_type=page --post_title='Welcome to a New Dawn' --post_content='Read on for some amazing insights.' --post_status=publish

Conclusion

We've just scratched the surface of what you can do with the WP-CLI. But hopefully, you'll now have enough confidence to delve deeper into the WP-CLI and experiment with more advanced commands.

We learned what the WP-CLI is and how useful it can be in your day-to-day WordPress development. Even though the commands we covered were rather basic, they were still pretty useful!

This was the first time I'd personally used the WP-CLI, and in retrospect I can honestly say I don't know how I managed without it. It's definitely something I see myself using a lot more.

I'd like to get some experience with much more complex commands next to really see what you can do with the WP-CLI.

Some users, particularly beginners, could be put off by the default recommended installation process, though. This is a shame as the WP-CLI is extremely useful and all WordPress developers should at least check it out.

It's great fun, as well as being useful. If you have access to DesktopServer then definitely use that to install WP-CLI—it's really a no-brainer.

Finally, if you're interested in more WordPress development, don't forget to check out the other WordPress material we have here on Envato Tuts+.

Do you already use the WP-CLI, or was this your first time experimenting with it? If so, how did you get on? I'd love to hear your comments!