An Introductory Guide to Managing WordPress with WP-CLI

This article provides an introductory guide to WP-CLI, a command-line tool that was created to make developers’ lives easier, allowing them to manage a WordPress site through the command line rather than through the usual admin interface.

WP-CLI was created by Daniel Bachhuber over a decade ago. Since then, it’s become an indispensable tool in every advanced WordPress developer’s arsenal — “deployed and relied upon by almost every major user of WordPress”, according to Matt Mullenweg. Since 2016, WP-CLI has been an official WordPress CLI tool.

WP-CLI is used for installing and setting up a WordPress website, changing its options, administering users, and a host of other things. It can be leveraged to significantly speed up developers’ workflows.

WP-CLI comes as a phar file — short for PHP Archive. It’s a standard for packaging multiple PHP files and other resources as a single application — for simpler distribution and installation.

Installation

WP-CLI presumes, obviously, that we have access to the system shell. This will be pretty straightforward on Linux and macOS systems — particularly on servers — as WordPress is served almost universally from Linux machines. If we have dedicated server hosting, or cloud hosting like AWS, Alibaba Cloud, etc., or if we’re using a VPS from Digital Ocean, Vultr, Linode and the like, SSH comes as a default access option, but these days many shared hosts offer SSH access options. (Some might even come with WP-CLI preinstalled.)

For Windows users, WP-CLI can be installed via Composer, but we recommend readers get themselves acquainted with Windows Subsystem for Linux, because it makes it possible to have a native Linux environment available, along with Bash, package manager like APT, etc. WordPress is a PHP app, and PHP’s native environment is Linux.

Further code samples presume we’re using Linux or a Unix-type system.

To fetch the WP-CLI phar archive, we usecurl or wget:

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

This downloads our archive to the current directory. Then we make it executable:

chmod +x wp-cli.phar

We them move it so it’s available as a wp command:

sudo mv wp-cli.phar /usr/local/bin/wp

Now we have a wp command available:

Now, upon typing the wp command, it displays all the options for us, and possible parameters. One caveat: if we’re running as the root user, we need to add --allow-root to our commands:

Now that we have it set up, we can explore the commands, and possible usage scenarios.

WP-CLI Commands

WP-CLI aims to offer a fast alternative to the WordPress web admin interface. There are chunks of code or functionality that offer simple, precise interfaces for performing complex tasks. Beside the bundled commands, WP-CLI defines an API for integrating third-party commands — WP_CLI::add_command(). These can be distributed either as standalone packages, or as part of WordPress plugins or themes.

In this guide, we’ll review bundled commands — those that come with the default WP-CLI installation — and some more notable third-party commands.

Commands can come as basic, one-argument commands like wp somecommand, or as subcommands under the base command namespace, such as wp somecommand subcommand.

wp core

The wp core subcommand is a command/namespace that consists of sucommands that deal with WordPress core — so we can download, install, update, convert to multisite and get information about our WordPress core version:

• wp core download will download the latest version of WordPress into the current directory
• wp core install runs the standard WordPress installation process, with options like --url=somewebsite.com, --title=SomeWebsite, --admin_user=someusername, --admin_password=somepassword and --admin_email=some@email.com
• wp core multisite-install installs a new multisite WordPress installation, and wp core multisite-convert converts a regular installation into multisite.
• wp core update will update WordPress to a newer version, and wp core update-db will update the database.

More details on wp core can be found in the documentation.

WP-CLI really shines when we combine its commands in Bash scripts, so we can combine, for example, wp core download and wp core install into a single Bash command and streamline the installation.

Worth noting here is that before we run the installation, we need to create a wp-config.php file, with database credentials and other details needed for the installation.

WP-CLI provides a wp config create command for this.

wp config

wp config is a namespace for commands that deal with WordPress configuration.

• wp config list lists all the configuration variables:

  

• wp config create — as we said — creates configuration file with variables we provide, like wp config create --dbname=somedb --dbuser=someuser --dbpass=somepass, and other variables, as outlined in the docs

• wp config get (for example, wp config get table_prefix) fetches specific config variables from wp-config.php

• wp config set, similarly, sets config variables

More of the wp config details can be found here.

wp cap is interesting for administering user roles and capabilities. We can add and remove capabilities from particular roles.

wp cron is a command namespace for testing, running and deleting WP-Cron events. wp cron event list, for example, would give us the output looking something like this:

Then we could delete events with something like wp cron event delete wsal_cleanup — or reschedule them, etc.

Sometimes, in the course of updating content, developing, making changes, we’ll find that refreshing a WordPress page will not show the changes we made. Many times this has resulted in a frantic search, trying to find what we did wrong.

Often it’s a cache issue. WordPress Object Cache, by default, isn’t persistent, so the need to clean the object cache will be exacerbated with the use of plugins that persist object cache across requests (and this is usually the case).

wp cache is a namespace that contains commands for handling the WP Object Cache.

wp cache flush is a command that flushes the whole cache. It’s a no-brainer — a simple, oft-used command that doesn’t require any other parameters, and purges everything from the cache.

wp cache contains other commands, as well, that can be used for very atomic management of cache items.

wp cache add, wp cache delete, wp cache get, wp cache set, wp cache replace and other commands make it possible to list, inspect, add, change or delete specific values from the object cache.

WordPress transients are another element of WP caching strategy, which is persistent by default, and can play a part in WordPress’s overall performance. It’s not unheard of that many plugins liberally use WordPress transients, which can get cluttered and slow down the website.

The wp transient namespace contains commands to delete, get or set transients.

Another element in the WordPress caching system that sometimes requires flushing, and has probably caused hours and hours of confusion for the beginners, are WordPress permalinks.

wp rewrite — wp rewrite flush in particular — makes it possible to flush rewrite rules (permalinks). We can also list rewrite rules.

wp db contains commands for managing a WordPress database. Insights, repair, optimization, search, various queries. We can also export or import the database.

wp eval and wp eval-file can be used to execute some code in the context of our WordPress installation.

wp export and wp import export and import content in WXR format.

wp option contains commands for managing, getting and setting WordPress options.

wp scaffold contains commands that create boilerplate or starting code for plugins, themes, child themes, Gutenberg blocks, post types, taxonomies — thus shortening the path to get them running.

wp search-replace does search-replace on a database with strings we provide it as arguments. This comes very handy when we migrate the database from one website to another, and need to change URLs. For example, when we create a staging website, or move a database from staging to production website.

WordPress serializes content strings in the database, so doing a raw search–replace on a database in some editor wouldn’t work; it would, in fact, break the website.

wp shell is particularly interesting, as it allows us to enter a WordPress repl — a live shell environment of our WordPress installation. There we have full access to everything that some active plugin may have available. We can write code, load code from files, execute functions, observe or inspect output from functions. It makes it very easy to test out new code without browser refresh cycles.

wp user is for managing, updating, deleting and changing roles of users.

These are some of the default, built-in commands. Detailed documentation of all the commands is available in the WordPress developer docs.

wp plugin makes it possible to list, install, activate, deactivate and delete plugins, and to write scripts that automate installation of multiple plugins in bulk. wp plugin list might give us output looking something like this:

wp theme does the same, only for themes.

wp package is a command namespace for managing WP-CLI packages. With wp package install somepackagename we can install third-party packages that are added to the WP-CLI Package index. Some noteworthy packages/commands are: wp usergen cli, which creates random users for testing; db checkpoint, which creates db snapshots; WP-CLI buddypress, which contains a number of BuddyPress-related commands; WP-CLI size, which shows database and table sizes; wp hook, which shows callback functions registered for a particular filter or action hook; query debug, which debugs the performance of queries; and faker, which helps us create filler posts for development purposes.

There are many other packages/commands maintained by the community. The full list can be foud here.

Conclusion

In this guide, we introduced WP-CLI and covered its main commands. We also introduced some of its third-party packages, but this is in no way complete reference. With WP-CLI, the usage possibilities and scenarios are virtually endless.