Advertisement
  1. Code
  2. WordPress
Code

What Is WP-CLI? A Beginner’s Guide

by
Difficulty:BeginnerLength:LongLanguages:

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.

Installing on macOS

Open up a terminal window and type in the following:

This will download the WP-CLI Phar file to your computer. Let’s check everything’s OK by testing the WP-CLI archive.

You should see output similar to the following:

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:

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:

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

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!

Installing WP-CLI Using DesktopServer

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

Access WP-CLI via the web browser
Accessing WP-CLI via WordPress

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.

Preparing to use WP-CLI

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.

Let's now test our installation of WP-CLI. This is our first command…

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

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

How about a list of all the themes currently installed?

Notice how we get useful information too, such as the status of a theme and its version, as well as if an update is available.

We can do the same for plugins.

We can make use of parameters to refine the list of plugins.

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).

We can also only show plugins that fulfill specific criteria.

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:

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:

Let's output a list of plugins again, to make sure Jetpack was installed, but this time just list the plugin name.

We can install themes in a similar way:

And let's just check the Twenty Eleven theme was installed correctly:

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:

To activate a plugin, use the activate command.

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

To delete a plugin, use the delete command.

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.

First, let's output the current list of posts.

Now, let's generate some posts.

Let's take a look again at the updated post list.

As you can see, five new posts have been created, each one with a generic title and no post content. We can generate any number of posts and for any post type.

This generates three new pages with generic titles and no page content. I'm not too sure about how useful mass post creation is. However, it could be pretty useful for testing purposes.

If we want to create individual posts then we do have full control over post content. Let's create a single post with a specific title and sample content.

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).

We can also update existing posts by using the update command.

Make sure the post ID is correct; otherwise, you'll get a Warning: Invalid post ID error message. And again, you can update any post type, not just posts!

As you'd expect, you can delete posts via the WP-CLI too.

This will send the post to trash. If you want to bypass this and just permanently delete a post then add the --force parameter.

Overall, I think it's pretty intuitive to manage posts via the WP-CLI. It doesn't feel like I'd have to remember lots of details every time I want to create or update a post.

This is great as it means I'm far more likely to keep coming back to the WP-CLI rather than sneaking back to using the cosy WordPress admin user interface I'm more accustomed to.

WordPress Comments

Managing comments is pretty similar to posts. To see all the comments on your site, use this command:

Be careful, though—this might take a while if you have a lot of comments on your site!

To create a comment, use the create command we're now familiar with.

Notice that to generate a comment, we needed to specify an ID of an existing post, as well as the comment content.

Just like we did for posts, mass comments can also be easily generated.

Make sure to specify the count parameter if you don't want 100 dummy comments generated, as 100 is the default!

To delete a comment, simply use the following command with the ID of your comment and optionally the --force parameter if you want to skip sending it to trash.

Remember, though, the Id here is a comment ID and not a post ID.

Recommended WP-CLI Resources

That's it for our basic introduction to the WP-CLI. Below is a list of resources if you want to dig a little deeper and expand your knowledge.

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!

Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.