An Introductory Guide to Managing WordPress with WP-CLI

Share this article

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:

Adding --allow-root to enable running as the root user

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:

    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:

wp cron output

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 rewritewp 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:

An example of wp plugin list output

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.

Frequently Asked Questions (FAQs) about WP-CLI

What is the difference between WP-CLI and WordPress Dashboard?

WP-CLI and WordPress Dashboard are both tools used to manage WordPress sites, but they operate differently. The WordPress Dashboard is a graphical user interface (GUI) that allows you to manage your site using a web browser. On the other hand, WP-CLI is a command-line interface (CLI) tool that allows you to manage your WordPress site from a terminal or command prompt. This means you can perform tasks such as installing plugins, updating the WordPress core, and creating backups without using a web browser.

How do I install WP-CLI on my server?

To install WP-CLI on your server, you need to download the WP-CLI phar file using curl or wget, make it executable, and move it to a location in your PATH. Here’s a step-by-step guide:


1. Download the WP-CLI phar file using curl or wget:
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
2. Make the WP-CLI phar file executable:
chmod +x wp-cli.phar
3. Move the WP-CLI phar file to a location in your PATH:
sudo mv wp-cli.phar /usr/local/bin/wp
After these steps, you should be able to run WP-CLI commands using the wp command.

How can I update WP-CLI?

You can update WP-CLI using the wp cli update command. If a new version is available, WP-CLI will download and install it. If your WP-CLI is already up to date, it will display a message saying “WP-CLI is at the latest version.”

Can I use WP-CLI to manage multiple WordPress sites?

Yes, you can use WP-CLI to manage multiple WordPress sites. You just need to navigate to the directory of the WordPress site you want to manage before running WP-CLI commands. For example, if you have a WordPress site in a directory called mysite, you can navigate to this directory using the cd mysite command, and then run WP-CLI commands for this site.

How can I use WP-CLI to install a WordPress plugin?

You can use the wp plugin install command to install a WordPress plugin. For example, to install the Akismet plugin, you would run the following command:
wp plugin install akismet
After running this command, WP-CLI will download and install the Akismet plugin. You can then activate the plugin using the wp plugin activate command.

How can I use WP-CLI to update the WordPress core?

You can use the wp core update command to update the WordPress core. This command will check for a new version of WordPress, and if one is available, it will download and install it. If your WordPress core is already up to date, it will display a message saying “WordPress is up to date.”

How can I use WP-CLI to create a backup of my WordPress site?

You can use the wp db export command to create a backup of your WordPress site’s database. This command will create a .sql file containing all the data in your WordPress database. You can then download this file for safekeeping.

Can I use WP-CLI on a Windows server?

Yes, you can use WP-CLI on a Windows server. However, you will need to install a compatibility layer like Cygwin or use a tool like Git Bash that provides a Unix-like command-line environment.

How can I use WP-CLI to manage WordPress users?

You can use WP-CLI to manage WordPress users using the wp user command. This command allows you to perform tasks such as creating new users, updating user information, and deleting users. For example, to create a new user, you would run the following command:
wp user create username email@example.com --role=administrator
This command will create a new user with the username username, the email address email@example.com, and the role of administrator.

How can I get help with WP-CLI commands?

You can get help with WP-CLI commands using the wp help command. This command will display a list of all available WP-CLI commands, along with a brief description of what each command does. You can also get help with a specific command by typing wp help followed by the name of the command. For example, to get help with the wp plugin install command, you would type wp help plugin install.

Tonino JankovTonino Jankov
View Author

Tonino is a web developer and IT consultant who's dived through open-source code for over a decade. He's also a crypto enthusiast, Linux fan, and moderate libertarian.

WordPressWordPress-hubWordPress-toolswp-cli
Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week