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.

Installing on macOS

Open up a terminal window and type in the following:

$ curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

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

php wp-cli.phar --info

You should see output similar to the following:

PHP binary:    /usr/bin/php
PHP version:	5.6.30
php.ini used:
WP-CLI root dir:	phar://wp-cli.phar
WP-CLI packages dir:
WP-CLI global config:
WP-CLI project config:
WP-CLI version:	1.1.0

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.

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…

wp --info

PHP binary:     C:xampplitephpphp.exe
PHP version:    5.5.24
php.ini used:   C:xampplitephpphp.ini
WP-CLI root dir:        C:xamppliteds-pluginsds-clivendorwp-cliwp-cli
WP-CLI packages dir:
WP-CLI global config:
WP-CLI project config:
WP-CLI version: 1.0.0

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.

wp core version

4.7.3

How about a list of all the themes currently installed?

wp theme list

+-----------------+----------+--------+---------+
| name            | status   | update | version |
+-----------------+----------+--------+---------+
| twentyfifteen   | inactive | none   | 1.7     |
| twentyseventeen | active   | none   | 1.1     |
| twentysixteen   | inactive | none   | 1.3     |
| twentyten       | inactive | none   | 2.2     |
+-----------------+----------+--------+---------+

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.

wp plugin list

+-------------+----------+--------+------------+
| name        | status   | update | version    |
+-------------+----------+--------+------------+
| akismet     | inactive | none   | 3.3        |
| hello       | inactive | none   | 1.6        |
| theme-check | inactive | none   | 20160523.1 |
+-------------+----------+--------+------------+

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

wp plugin list --fields=name,version

+-------------+------------+
| name        | version    |
+-------------+------------+
| akismet     | 3.3        |
| hello       | 1.6        |
| theme-check | 20160523.1 |
+-------------+------------+

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.

wp plugin list --status=inactive

+-------------+----------+--------+------------+
| name        | status   | update | version    |
+-------------+----------+--------+------------+
| akismet     | inactive | none   | 3.3        |
| hello       | inactive | none   | 1.6        |
| theme-check | inactive | none   | 20160523.1 |
+-------------+----------+--------+------------+

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.

wp plugin

usage: wp plugin activate [<plugin>...] [--all] [--network]
   or: wp plugin deactivate [<plugin>...] [--uninstall] [--all] [--network]
   or: wp plugin delete <plugin>...
   or: wp plugin get <plugin> [--field=<field>] [--fields=<fields>] [--format=<format>]
   or: wp plugin install <plugin|zip|url>... [--version=<version>] [--force] [--activate] [--activate-network]
   or: wp plugin is-installed <plugin>
   or: wp plugin list [--<field>=<value>] [--field=<field>] [--fields=<fields>] [--format=<format>]
   or: wp plugin path [<plugin>] [--dir]
   or: wp plugin search <search> [--page=<page>] [--per-page=<per-page>] [--field=<field>] [--fields=<fields>] [           --format=<format>]
   or: wp plugin status [<plugin>]
   or: wp plugin toggle <plugin>... [--network]
   or: wp plugin uninstall <plugin>... [--deactivate] [--skip-delete]
   or: wp plugin update [<plugin>...] [--all] [--format=<format>] [--version=<version>] [--dry-run]

See 'wp help plugin <command>' for more information on a specific command.

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.

wp plugin list --format=json

[{"name":"akismet","status":"inactive","update":"none","version":"3.3"},{"name":"hello","status":"inactive","update":"none","version":"1.6"},{"name":"theme-check","status":"inactive","update":"none","version":"20160523.1"}]

wp plugin list --format=csv

name,status,update,version
akismet,inactive,none,3.3
hello,inactive,none,1.6
theme-check,inactive,none,20160523.1

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:

wp plugin install jetpack

Installing Jetpack by WordPress.com (4.8.2)
Downloading install package from https://downloads.wordpress.org/plugin/jetpack.4.8.2.zip...
Unpacking the package...
Installing the plugin...
Plugin installed successfully.
Success: Installed 1 of 1 plugins.

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

wp list plugin --fields=name

+-------------+
| name        |
+-------------+
| akismet     |
| hello       |
| jetpack     |
| theme-check |
+-------------+

We can install themes in a similar way:

wp theme install twentyeleven

Installing Twenty Eleven (2.5)
Downloading install package from https://downloads.wordpress.org/theme/twentyeleven.2.5.zip...
Unpacking the package...
Installing the theme...
Theme installed successfully.
Success: Installed 1 of 1 themes.

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

wp theme list

+-----------------+----------+--------+---------+
| name            | status   | update | version |
+-----------------+----------+--------+---------+
| twentyeleven    | inactive | none   | 2.5     |
| twentyfifteen   | inactive | none   | 1.7     |
| twentyseventeen | active   | none   | 1.1     |
| twentysixteen   | inactive | none   | 1.3     |
| twentyten       | inactive | none   | 2.2     |
+-----------------+----------+--------+---------+

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.

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

wp post list

+----+---------+---------+---------+---------+
| ID | post_ti | post_na | post_da | post_st |
|    | tle     | me      | te      | atus    |
+----+---------+---------+---------+---------+
| 1  | Hello w | hello-w | 2017-04 | publish |
|    | orld!   | orld    | -04 09: |         |
|    |         |         | 18:12   |         |
+----+---------+---------+---------+---------+

Now, let’s generate some posts.

wp post generate --count=5

Generating posts  100% [=============] 0:03 / 0:02

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

wp post list

+----+---------+---------+---------+---------+
| ID | post_ti | post_na | post_da | post_st |
|    | tle     | me      | te      | atus    |
+----+---------+---------+---------+---------+
| 32 | Post 2  | post-2  | 2017-04 | publish |
|    |         |         | -14 19: |         |
|    |         |         | 01:24   |         |
| 33 | Post 3  | post-3  | 2017-04 | publish |
|    |         |         | -14 19: |         |
|    |         |         | 01:24   |         |
| 34 | Post 4  | post-4  | 2017-04 | publish |
|    |         |         | -14 19: |         |
|    |         |         | 01:24   |         |
| 35 | Post 5  | post-5  | 2017-04 | publish |
|    |         |         | -14 19: |         |
|    |         |         | 01:24   |         |
| 36 | Post 6  | post-6  | 2017-04 | publish |
|    |         |         | -14 19: |         |
|    |         |         | 01:24   |         |
| 1  | Hello w | hello-w | 2017-04 | publish |
|    | orld!   | orld    | -04 09: |         |
|    |         |         | 18:12   |         |
+----+---------+---------+---------+---------+

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.

wp post generate --post_type=page --count=3

Generating posts  100% [=============] 0:02 / 0:03

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.

 wp post list --post_type=page

+----+---------+---------+---------+---------+
| ID | post_ti | post_na | post_da | post_st |
|    | tle     | me      | te      | atus    |
+----+---------+---------+---------+---------+
| 42 | Page 2  | post-2  | 2017-04 | publish |
|    |         |         | -14 19: |         |
|    |         |         | 06:21   |         |
| 43 | Page 3  | post-3  | 2017-04 | publish |
|    |         |         | -14 19: |         |
|    |         |         | 06:21   |         |
| 44 | Page 4  | post-4  | 2017-04 | publish |
|    |         |         | -14 19: |         |
|    |         |         | 06:21   |         |
| 22 | Title   | title   | 2017-04 | publish |
|    |         |         | -07 15: |         |
|    |         |         | 42:27   |         |
| 2  | Sample  | sample- | 2017-04 | publish |
|    | Page    | page    | -04 09: |         |
|    |         |         | 18:12   |         |
+----+---------+---------+---------+---------+

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.

wp post create --post_title='Just a Post' --post_content='I wandered lonely as a cloud.' --post_status='publish'

Success: Created post 45.

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

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

wp post update 45 --post_content='I just updated the post content via the WP-CLI.' --post_status='publish'

Success: Updated post 45.

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.

wp post delete 45

Success: Trashed post 45.

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

wp post delete 45 --force

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:

wp comment list

+------------+-----------------+---------------------+------------------+-----------------------+-------------------------+
| comment_ID | comment_post_ID | comment_date        | comment_approved | comment_author        | comment_author_email    |
+------------+-----------------+---------------------+------------------+-----------------------+-------------------------+
| 1          | 1               | 2017-04-04 09:18:12 | 1                | A WordPress Commenter | [email protected] |
+------------+-----------------+---------------------+------------------+-----------------------+-------------------------+

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.

wp comment create --comment_post_ID=1 --comment_content='Just adding my 2 cents worth!'

Success: Created comment 24.

wp comment list

+------------+-----------------+---------------------+------------------+-----------------------+-------------------------+
| comment_ID | comment_post_ID | comment_date        | comment_approved | comment_author        | comment_author_email    |
+------------+-----------------+---------------------+------------------+-----------------------+-------------------------+
| 24         | 1               | 2017-04-14 19:24:45 | 1                |                       |                         |
| 1          | 1               | 2017-04-04 09:18:12 | 1                | A WordPress Commenter | [email protected] |
+------------+-----------------+---------------------+------------------+-----------------------+-------------------------+

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.

wp comment generate --count=3 --post_id=1

Generating comments  100% [==========] 0:02 / 0:03

wp comment list

+------------+-----------------+---------------------+------------------+-----------------------+-------------------------+
| comment_ID | comment_post_ID | comment_date        | comment_approved | comment_author        | comment_author_email    |
+------------+-----------------+---------------------+------------------+-----------------------+-------------------------+
| 26         | 1               | 2017-04-14 19:27:54 | 1                |                       |                         |
| 27         | 1               | 2017-04-14 19:27:54 | 1                |                       |                         |
| 25         | 1               | 2017-04-14 19:27:53 | 1                |                       |                         |
| 24         | 1               | 2017-04-14 19:24:45 | 1                |                       |                         |
| 1          | 1               | 2017-04-04 09:18:12 | 1                | A WordPress Commenter | [email protected] |
+------------+-----------------+---------------------+------------------+-----------------------+-------------------------+

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.

wp comment delete 26 --force

Success: Deleted comment 26.

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!