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.

--ADVERTISEMENT--

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.

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

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