An introduction to WP-CLI

An introduction to WP-CLI

Command Line Interfaces (CLI’s) are a developer’s best friend. WP-CLI, the WordPress Command Line Interface (WP-CLI) is an indispensible component of any serious WordPress developers toolkit.

If you are a developer working in the WordPress ecosystem and managing dozens of WordPress sites (or more), you can drastically reduce your workload, whilst increasing your efficiency and productivity by installing and utilising the WordPress Command Line Interface.

No wonder then, WP-CLI development has been brought under the fold of WordPress.org. WP-CLI, alongside the REST API and the new Gutenberg editor, will play a central part in development for the WordPress platform going forward.

In this short tutorial, we will install WP-CLI to a RunCloud managed server. After that, we will take a (very) brief look at the anatomy of some of the commands that make WP-CLI so useful. We will end the tutorial by creating a global WP-CLI configuration file, that we will use in future tutorials.

In my tutorial examples, I will be logging in to a server using passwordless login via SSH. I will be doing this as a superuser with root administrative privileges. When necessary I will be using the sudo*** command to execute commands as an administrator. If you don’t have a **superuser account, you can create one by following this tutorial. Alternatively you can throw caution to the wind and live life on the edge, by just logging in to your server as root user and omitting the sudo command.

This article contains preformatted codeblocks containing code examples that can be easily cut and paste. However if you are viewing the tutorial as a Facebook Instant Article these will not be visible, due to Facebook’s policy of not supporting preformatted text. I have endeavored to include Terminal screenshots illustrating each code example for those users.

Install WP-CLI

Login to your server and download the wp-cli.phar php archive file using wget or curl. After that Then check the file is not corrupted and working using the –info subcommand which should output a bunch of information about your PHP installation. This information will also include directories, and paths related to WP-CLI: :

$ ssh <your-superuser>@<your-server-ip-address>
$ curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
$ php wp-cli.phar --info

Your terminal should output a bunch of information about your PHP installation. This information will also include directories, and paths related to WP-CLI:

Download and test the WP-CLI PHP Archive file
Download and test the WP-CLI PHP Archive file

Now we need to make the WP-CLI PHP archive file executable, and move it somewhere in our PATH. Then we can run WP-CLI commands from anywhere on the server using the wp command. Let’s check the installation information again, but this time with wp –info:

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

Make the WP-CLI PHP Archive Executable, and move it into you PATH
Make the WP-CLI PHP Archive Executable, and move it into you PATH[/caption]

WP-CLI Commands

The anatomoy of a WP-CLI Command

A typical WP-CLI command structure starts with wp followed by a command, then a subcommand and finally –options-with-value=value and –options-without-value.

$ wp <command> <subcommand> --<option-with-value>=<option-value> --<option-without-value>
$ wp core update --version=4.9.1 --force

Some Common WordPress Management Task Commands

Some of the most common repetitive tasks, for someone managing or developing WordPress sites, concern the updating or WordPress Core, Plugins and Themes. Let’s look at some of these commands to quickly demonstrate the usefulness of WP-CLI

First, change directory into the root folder of one of your WordPress sites.

$ cd ~/webapps/an-example

Some WP-CLI Core Commands

We can easily check the WordPress version, and update it.

$ wp core version
$ wp core update

Check your version of WordPress Core and update it easily!
Check your version of WordPress Core and update it easily!

Sometimes, we may want to roll back our WordPress version. For example, perhaps there is a conflict with a plugin that is vital to the site. That’s no problem we can use the –force option to rolll back to a previous version:

$ wp core version
$ wp core update --version=4.9.1 --force

Roll back your version of WordPress just as easily
Roll back your version of WordPress just as easily

Some WP-CLI Plugin Commands

We can list the plugins our WordPress sites plugins, and see their version, whether there is an update, and their activation status easily using the ‘list’ command. My example site is a fresh install so it includes those wonderful complimentary plugins included in core, ‘Akismet’ and ‘Hello Dolly’. I am joking, I hate those plugins and the first thing I do on any new site is delete them. Now its easier than ever, just use the delete command.

When executing actions on plugins or themes, you use the slug from the WordPress repository.

$ wp plugin list
$ wp plugin delete akismet hello

Check your plugins and delete them using WP-CLI
Check your plugins and delete them using WP-CLI

Other plugins are much more popular, let’s install one and activate it:

$ wp plugin install regenerate-thumbnails --activate

Install a plugin with a simple command
Install a plugin with a simple command.

Rolling back a Plugin with ease!

A common problem you may encounter is when an update to a plugin leads to a conflict. Sometimes you need to make the choice to roll back the plugin to the previous version until there is a fix. If you use the browser and a GUI, this is a bit of a headache. First you need to deactivate the plugin, then delete it, then you need to search for it’s previous version at WordPress.org, download it locally, upload it via the WP-Admin plugin screen, install it, then activate it. This is an 7 step process and an utter annoyance.

With WP-CLI you can say goodbye to those 7 steps forever. Now you just need update to a previous version. In my case, I will roll back ‘Regenerate Thumbnails’ to the previous version.

$ wp plugin update regenerate-thumbnails --version=3.0.1

Rolling back a plugin is no longer an 7 step nightmare!
Rolling back a plugin is no longer an 7 step headache!

Some WP-CLI Theme Commands

The WP-CLI Theme command utilizes the same subcommands as the WP-CLI Plugin command, so you can list, search for, install, uninstall, activate, deactivate, update, rollback and delete Themes. Let’s check our themes and delete any unnecessary ones.

$ wp theme list
$ wp theme delete twentyfifteen twentysixteen

List out your Themes and delete the redundant ones.
List out your Themes and delete the redundant ones.

How about rolling back our active theme to a previous version:

$ wp theme update twentyseventeen --version=1.3

Rolling back a Theme is just as easy
Rolling back a Theme is just as easy!

You get the picture.

Believe me when I tell you, this is just scratching the surface. A full list of WP-CLI commands can be found on the WordPress.org Developers Site.

In a future tutorial I will be taking a much deeper dive into some of the most useful commands. Another great thing about WP-CLI is it’s extensibility, we will also look into this in a later tutorial.

WP-CLI configuration files

WP-CLI uses YAML configuration files to set default configurations and parameters. These can be set at either the global (server) level, or at a local project directory level.

Configuration Precedence

The configuration files are interpreted in an order of precedence, from highest to lowest as follows:

  1. Command-line arguments.
  2. A local wp-cli.local.yml file inside the current working directory (or upwards).
  3. Another local wp-cli.yml file inside the current working directory (or upwards).
  4. ~/.wp-cli/config.yml Global configuration file.
  5. WP-CLI defaults.

Create a Global Configuration File

We are going to create a Global Configuration file, ‘~/.wp-cli/config.yml’ and add soem default configuration parameters.

The ‘.wp-cli’ directory inside our user home directory is not automatically created. First let’s add that directory mkdir ~/.wp-cli, change into it cd ~/.wp-cli, and create and open the configuration file for editing nano config.yml.

$ mkdir ~/.wp-cli && cd ~/.wp-cli
$ nano config.yml

Inside the ‘config.yml’ file I have added the following lines. These are just examples that are suitable for my development workflow:

# Global parameter defaults
disabled_commands:
  - db drop

# Subcommand defaults
config create:
    dbuser: example_database
    dbpass: example_user
    extra-php: |
        define( 'WP_CACHE', true );

Set your WP-CLI defaults and Global Parameters in the configuration file.
Set your WP-CLI defaults and Global Parameters in the configuration file.

Global Parameter Defaults

With WP-CLI it is very easy to work on the Database. Some of the Database commands are the most powerful, but risky. To mitigate some of that risk, I have disabled the ‘db drop’ command. I can perform tasks on my database now, but I can’t drop all the tables.

Subcommand Defaults

I have also created some defaults for the ‘config create’ subcommand.

Often we use the same database user and password for many different installations. Here I have set a user and password as a default, now when I use the ‘wp config create’ command, I would no longer have to set these specific sub commands and they would default to my preferred parameter.

I always use caching with my WordPress sites, which usually means editing the ‘wp-config.php’ file, but here I have set it up so that whenever I create a ‘wp-config.php’ file with WP-CLI, it already includes this PHP definition. We often create sites with similar configurations, using this WP-CLI configuration file means we can stop repeating the same tasks over and over.

You can find out more about WP-CLI Global parameters and Configuration files here.

Check Configuration File Locations

Now when you check wp –info, you will see the location of your Global configuration file in the output.

$ wp --info

Check the location of your Global Configuration file with 'wp --info'
Check the location of your Global Configuration file with ‘wp –info’

Where next?

As I mentioned earlier, this is just skimming the surface of the possibilities with the WordPress Command Line Interface. Not only the possibilities of the core WP-CLI commands, but the potential due to the packages that extend its abilities even further.

You may be asking yourself, “Is it really that much faster? I mean, in this tutorial, we are having to change into the WordPress root directories to issue commands individually on each site, one at a time.”

Well…. You are right, but this tutorial was just a basic demonstration.

In following tutorials we will dive deeper into the potential. You will see how some simple commands completely negate the need for many popular plugins. Learn how to manage your content, databases, posts, pages, speed up custom development and more.

In another tutorial we will set up Aliases in our configuration file. We will use Aliases on a server, to manage multiple WordPress sites, on the same server, simultaeneously with single commands. We will then learn how to use Aliases and SSH to manage hundreds of WordPress sites across many multiple servers, with a single command, all from your local machine.

Leave a Reply

Your email address will not be published. Required fields are marked *