WP-CLI: first steps on WordPress’ command line tools

Before any trend of using Composer, NPM, Yarn or any other command line tool within WordPress’ themes and plugins development, devs have already been using a set of command line tools which had been particularly designed for managing WP instances.

WP-CLI is a command line tool which is extensible, comprehensive and easy to use. Even for tasks like plugins’ updating, reinstalling the WP core or optimizing the database, it should be the first option for those who are properly developing under a WP-based environment.

Most popular VPNs and cloud servers already have WP-CLI installed and running, but sometimes we need to install and setup it before using the command line tools. If this is your case, just access the SSH prompt in your server or cloud and proceed the installation, following a few steps:

# First, download WP-CLI package using Curl (or Wget)
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar  
# Secondly, we want to make wp-cli.phar executable from the prompt
chmod +x wp-cli.phar
# Finally, we move it to a user directory as wp command
sudo mv wp-cli.phar /usr/local/bin/wp

First contact

Well, if the installation happened with no errors or exceptions, that means you can already use the wp command. From your SSH prompt, just type wp and enter. This will list all general subcommands available (as shown in the picture). There is a lot we can do with WP-CLI, so lets just keep this article in the main and most basic features.

Basically, the initial purpose of WP-CLI is to provide a site admin with tools for managing every single aspect of a website, without the need of logging in the back-end. Also, it has tools for optimizing and dealing with assets, users and the database – meaning that most plugins doing the same job can be simply deleted from your instance.

Some basic commands

WP-CLI comes with some commands and is extensible, which means that new commands and tools can be added. However, for this first contact, let’s learn the basics. Let’s start with some routines with plugins. First, we will retrieve a list of all plugins, active or not, using the command line.

username@host [/var/www/html]# wp plugin list
+----------------+----------+-----------+---------+
| name           | status   | update    | version |
+----------------+----------+-----------+---------+
| akismet        | active   | available | 3.4     |
| google-captcha | active   | none      | 1.31    |
| hello          | inactive | none      | 1.6     |
| jetpack        | active   | none      | 5.3     |
| woocommerce    | active   | none      | 5.2     |
+----------------+----------+-----------+---------+

While getting the list, you can notice that Akismet plugin has an available update – so let’s update it using the command line, instead of logging in the backend for such:

username@host [/var/www/html]# wp plugin update akismet
Enabling Maintenance mode...
Downloading update from https://downloads.wordpress.org/plugin/akismet.3.3.4.zip...
Unpacking the update...
Installing the latest version...
Removing the old version of the plugin...
Plugin updated successfully.
Disabling Maintenance mode...
+---------+-------------+-------------+---------+
| name    | old_version | new_version | status  |
+---------+-------------+-------------+---------+
| akismet | 3.4         | 3.5         | Updated |
+---------+-------------+-------------+---------+
Success: Updated 1 of 1 plugins.

Following this first contact, before making any changes within your WP installation, you should be getting acquainted with the main WP-CLI commands. For such, the only you need to do is typing wp help and enter. That will list all available commands for WP-CLI (new ones that can be eventually added will also appear).

This gives you a list of all commands, and if you want to get more info on one of those commands particularly, all you need to do is using wp help <command>.

username@host [/var/www/html]# wp help role
DESCRIPTION

  Manages user roles, including creating new roles and resetting to defaults.

SYNOPSIS

  wp role <command>

SUBCOMMANDS

  create      Creates a new role.
  delete      Deletes an existing role.
  exists      Checks if a role exists.
  list        Lists all roles.
  reset       Resets any default role to default capabilities.

  See references for [Roles and Capabilities][1] and [WP User class][2].

  ---
  [1] https://codex.wordpress.org/Roles_and_Capabilities
  [2] https://codex.wordpress.org/Class_Reference/WP_User

EXAMPLES

    # List roles.
    $ wp role list --fields=role --format=csv
    role
    administrator
    editor
    author
    contributor
    subscriber

    # Check to see if a role exists.
    $ wp role exists editor
    Success: Role with ID 'editor' exists.

    # Create a new role.
    $ wp role create approver Approver
    Success: Role with key 'approver' created.

    # Delete an existing role.
    $ wp role delete approver
    Success: Role with key 'approver' deleted.

    # Reset existing roles to their default capabilities.
    $ wp role reset administrator author contributor
    Success: Reset 3/3 roles.

GLOBAL PARAMETERS

  --path=<path>
      Path to the WordPress files.

  --url=<url>
      Pretend request came from given URL. In multisite, this argument is how the target site is specified.

  --ssh=[<scheme>:][<user>@]<host|container>[:<port>][<path>]
      Perform operation against a remote server over SSH (or a container using scheme of "docker", "docker-compose", "vagrant").

  --http=<http>
      Perform operation against a remote WordPress installation over HTTP.

  --user=<id|login|email>
      Set the WordPress user.

  --skip-plugins[=<plugins>]
      Skip loading all plugins, or a comma-separated list of plugins. Note: mu-plugins are still loaded.

  --skip-themes[=<themes>]
      Skip loading all themes, or a comma-separated list of themes.

  --skip-packages
      Skip loading all installed packages.

  --require=<path>
      Load PHP file before running the command (may be used more than once).

  --[no-]color
      Whether to colorize the output.

  --debug[=<group>]
      Show all PHP errors and add verbosity to WP-CLI output. Built-in groups include: bootstrap, commandfactory, and help.

  --prompt[=<assoc>]
      Prompt the user to enter values for all command arguments, or a subset specified as comma-separated values.

  --quiet
      Suppress informational messages.

(END)

This is the info and details just for the “role” command. WP-CLI offers a comprehensive help for all available commands, which means you can learn while using it.

Why struggling?

Those starting to code in WP constantly struggle to create post types, taxonomies or even use some complicated and advanced plugin and theme boilerplates to develop their first modules on WordPress. The fact is that WP-CLI not only can be used for managing an installation, but also to create new types, scaffold plugins, themes, generate code and even Gutenberg blocks.

With time, WP-CLI simple structures prove to be much easier and fast than intrincated starters and boilerplates using NPM dependencies and Composer. Of course you can get there, but if you are not used to those tools, you’d better start with the basics – and that is exactly what WP-CLI tools can provide.

In a next post, we will show how to develop a simple plugin and a Gutenberg’s block starting from WP-CLI’s scaffolding structure. Stay tuned!