A Beginner’s Guide to WP-CLI: What It Is & How to Use It

The traditional approach to managing a WordPress website is simple. You log in to the WordPress admin panel using a web browser and make changes to your website.

But this approach doesn’t work for users that manage multiple WordPress websites. It can be tedious to perform administrative tasks while switching between multiple tabs and windows and managing multiple access credentials all at once.

Luckily, there’s a solution to this problem. It’s called WP-CLI, aka the WordPress Command-Line interface.

WP-CLI is an open-source tool that lets you execute virtually any task you can perform in the WordPress admin using a command-line interface. And, that’s not all; it even lets you create custom commands for tasks unique to your website.

Curious to learn more? In this post, we’ll review everything you need to know about working with WP-CLI, including what it is, how to install it, and how to use it with your WordPress websites.

What is WP-CLI?

WP-CLI is an open-source tool that allows WordPress users to perform website administration tasks using a command-line interface. It serves as an alternative to the WordPress admin and even allows you to interact with your website remotely.

It’s worth pointing out that WP-CLI isn’t a WordPress plugin. It’s PHP-code packaged in a Phar — i.e., a PHP archive — that makes it easy to distribute the application. Thus, you can use WP-CLI without a WordPress website by installing it on a UNIX-like operating system.

How to Install WP-CLI

You can install WP-CLI in several ways, such as using Git, Composer, and Docker. However, the recommended installation method is using the Phar build.

Here’s how to install the latest WP-CLI version on your server:

Step 1: Check your prerequisites.

Before you install WP-CLI, make sure your server environment consists of:

1. UNIX-based Operating System
2. WordPress version 3.7+
3. PHP version 5.6 or above

If it does, move on to the next step. If not, you may have to do some digging to determine if your setup is compatible with WP-CLI.

Step 2: Download the WP-CLI Phar file.

Download the Phar file from the WP-CLI repo using either wget or curl. Here’s how to download the file using the curl command:

 

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

And, here's what it might look like for your WordPress site:

Step 3: Verify the Phar file.

Before you install WP-CLI, make sure the file is working by using the following command:

 

$ php wp-cli.phar --info

If you see an error, delete the file using the rm command, verify you’ve copied and pasted the download command correctly, and download the file again.

Step 4: Make the file executable.

To start using WP-CLI, you need to make the file “executable.” You can do this using the following command:

 

$ chmod +x wp-cli.phar

After this, you can start executing WP-CLI commands by typing php wp-cli.phar followed by the command. For example:

 

$ php wp-cli.phar cli update

Step 5: Move the file to your PATH.

Finally, to make it easy to access the WP-CLI, we’ll move the executable file to a folder in our PATH so we can call it from anywhere on our system using only wp.

 

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

After you’re done installing WP-CLI, you can start using it immediately. If you’re not sure where to start, it helps to understand the command syntax.

Basics of the WP-CLI Command Syntax

WP-CLI commands make it easy for users to perform complex tasks using precise instructions. They eliminate the need to interact with a browser and speed up the website administration process.

But addressing every possible use case through one application isn’t possible. Thus, WP-CLI only provides the commands necessary to perform administration tasks related to the WordPress admin.

Still, you can create custom commands for WP-CLI using its internal API — and that’s not all. WordPress developers can also create custom WP-CLI commands for plugins and bundle them within the plugin code or distribute them as standalone packages. A WP-CLI command usually consists of the primary command, a positional argument, and an associative argument.

Suppose you’re trying to install a plugin on your website from the CLI, you can use the following command syntax:

 

$ wp plugin install <plugin|zip|url>... [--version=<version>] [--force] [--activate] [--activate-network]

In the above example, wp plugin install is the primary command, <plugin|zip|url>... is the positional argument, and all items in the square brackets are associative arguments.

When executing the above WP-CLI command, you only need one positional argument to point WP-CLI to the plugin you’re trying to install. The associative arguments are optional. So, you can skip them, use one of them, or use multiple to suit your use case.

For example, you can install the WordPress Jetpack plugin using the following command that adds a positional argument to the primary command:

 

$ wp plugin install jetpack

Here's a live view of what this might look like on your site:

And, if you’d like to install and activate the plugin at the same time, you can add an associative argument as shown below:

 

$ wp plugin install jetpack --activate

This is what it would look like in action:

This eliminates the need to enter multiple commands via the command line.

How to Use the WP-CLI to Manage a WordPress Website

The WP-CLI offers hundreds of common commands and can support an unlimited number of custom commands. Thus, the possibilities of using WP-CLI to manage a WordPress website are effectively infinite.

To help you start, we’ve put together a list of examples that demonstrate how to use the WP-CLI for routine tasks.

1. Download and install WordPress.

You can use the WP-CLI to install WordPress by downloading or using a zip file.

To download WordPress from the WordPress.org servers, use the following command:

 

$ wp core download

Live Example:

This command downloads the core application files, verifies the MD5 checksum, and then extracts the files to the current directory. You can also specify a path by adding --path= followed by the direct path to the download destination at the end of the command.

After downloading WordPress, you’ll need to configure the wp-config using wp core config, update file permissions for the wp-config.php file, and then install WordPress using the below command:

 

$ wp core install --url=example.com --title=Example --admin_user=supervisor --admin_password=strongpassword --admin_email=info@example.com

Make sure you replace all values after the “=” in the associative arguments with the desired values.

2. Update & rollback WordPress versions.

You can also use WP-CLI to update WordPress or downgrade to an older version.

To update WordPress using the WP-CLI, run the following command:

 

$ wp core update

This command updates WordPress to the latest release available on WordPress.org. You can also add associative arguments to:

• define a path to a zip file to install WordPress.
• specify the version of WordPress.
• force WordPress to roll back to an older version.

Here’s how you could rollback WordPress from version 5.8.2 to 5.8.1:

 

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

As a general best practice, you should always use the latest version of WordPress. However, if you encounter issues such as plugin or theme incompatibilities, you can roll back to an older version until the developer releases a compatible update to their plugin.

3. Perform WordPress health checks.

You can also use WP-CLI to troubleshoot your WordPress installation using a WP-CLI package called WP Doctor. This software runs a series of checks for common WordPress issues such as failed updates, caching issues, and cron misconfigurations.

You can install the WP Doctor package using the following command:

 

$ wp package install git@github.com:wp-cli/doctor-command.git

Live Example:

After this, you can run a complete check using the following command:

 

$ wp doctor check --all

Live Example:

After the wp doctor command executes, it outputs the name and status of the checks performed and a message to help you diagnose any errors. This can save you hours of troubleshooting when your website goes down out of the blue.

4. Change your WordPress URL.

Generally, if you want to make changes to your WordPress URL, you can update it using:

• WordPress admin panel
• Database
• wp-config.php file

However, each of these comes with its own set of complexities. The WP-CLI offers a much cleaner method to update your website URL.

For example, if you want to update your WordPress URLs from HTTP to HTTPS, you can do so as follows:

 

$ wp option update home 'https://www.example.com'

$ wp option update siteurl 'https://www.example.com'

Live Example:

5. List all WordPress plugins.

WP-CLI enables you to output a detailed list of all plugins installed on your website with additional information such as their activation status, update availability, and version as follows:

 

$ wp plugin list

Live Example:

You can even add options or arguments to this command to modify its behavior. For example, to list the installed drop-ins on your website, you can use the following command:

 

$ wp plugin list --status=dropin

6. Install WordPress plugins.

You can also use WP-CLI to install a plugin on your WordPress website from the command line as follows:

 

$ wp plugin install <plugin|zip|url>…

For example, here’s how you can install and activate the HubSpot WordPress plugin on your website using the WP-CLI plugin command:

 

$ wp plugin install leadin --activate

Live Example:

You can even use the WP-CLI to update plugins using the wp plugin update command.

7. Uninstall WordPress plugins.

Although rare, sometimes, a plugin update might break your website. In such cases, the WP-CLI offers you an alternative method to uninstall plugins without using the WordPress admin.

To uninstall plugins on your WordPress website using the WP-CLI, you can use the wp plugin uninstall command. For example:

 

$ wp plugin uninstall hello

Live Example:

This command uninstalls and deletes the hello plugin. If you wish to uninstall the plugin without deleting it, you can use the following command:

 

$ wp plugin uninstall hello --skip-delete

8. Install WordPress themes.

Installing WordPress themes using the WP-CLI is quicker than doing it from the admin. You can do it using the wp theme install command as follows:

 

$ wp theme install twentytwenty

Live Example:

You can add the --activate option to the command to activate the theme after installing it and specify a theme version using the --version=<version> option.

9. Uninstall WordPress themes.

A poorly-developed theme can break your website. And, when you can’t access the WordPress admin, the only way to disable the theme is to either rename or delete the theme directory in the WordPress installation folder.

The WP-CLI offers an easier way to uninstall a theme. You can use the wp theme delete command to remove a theme from your website as follows:

 

$ wp theme delete twentytwenty

Live Example:

The wp theme delete command doesn’t delete an active theme by default. If you want to remove an active theme from your website, you’ll need to add the --force option to the end of the command.

10. Manage WordPress maintenance mode.

WordPress maintenance mode temporarily disables access to the front end of your website. This is important because it prevents website visitors from interacting with your website during theme or plugin updates.

However, sometimes, WordPress may remain in maintenance mode even after the update completes. And unfortunately, WordPress doesn’t allow you to disable the maintenance mode from the admin.

If your WordPress website is stuck in maintenance mode, you’ll need to access your WordPress installation folder via SSH and delete the .maintenance file in the root folder.

Alternatively, you can also use the WP-CLI to manage the maintenance mode of your website.

You can enable, disable, and check its status using the following commands:

 

$ wp maintenance-mode activate

$ wp maintenance-mode status

$ wp maintenance-mode deactivate

Live Example:

11. Manage user roles.

WordPress lets you assign user roles via the admin. And, if you need to customize a role, you can do it with a plugin or by editing the functions.php file.

The WP-CLI offers an easier way to create, assign, and remove user roles. It also helps you perform advanced user administration tasks such as listing and editing user capabilities and even destroying user sessions.

For example, you can create a new user role as follows:

 

$ wp role create designer Designer


You can then assign capabilities to the new role as follows:


$ wp cap add designer spectate

Finally, you can assign this role to an existing user using the following command:

 

$ wp user set-role 2 designer

Live Example:

Common WP-CLI Errors & How To Fix Them

When working with the WP-CLI, you can run into errors occasionally. Here are four common WP-CLI errors and their solutions.

1. Error: Can’t Connect to the Database

Generally, the “Error: Can’t connect to the database” message is shown when WP-CLI can’t connect to the website database. This connection issue could arise from several different factors, but the usual suspects are:

1. A multisite WordPress installation
2. MAMP is not using the MAMP PHP Binary
3. Incorrect database credentials in the wp-config.php file

The solution to this problem varies based on the cause. If you’re running a multisite installation, you’ll need to use the wp site command.

If you’re using MAMP and MAMP isn’t using the MAMP PHP Binary, you can configure PHP CLI to use MAMP’s PHP.

And, if the database credentials in wp-config.php are incorrect, update the values and rerun the command.

2. PHP Fatal Error: Allowed Memory Size of 999999 Bytes Exhausted (Tried To Allocate 99 Bytes)

You generally see this error message when your server runs out of memory.

WP-CLI uses Composer, a popular dependency manager, to manage WP-CLI packages. And, unfortunately, Composer can exhaust your server memory during tasks like package installs.

But the good news is that this one’s an easy fix. You can solve this problem by editing the PHP configuration file, aka php.ini. Use your preferred text editor and update the value for “memory_limit” to at least 512M or more, as demonstrated below.

Finally, restart PHP to update the configuration.

3. PHP Fatal Error: Call to Undefined Function

WP-CLI checks the wp-config.php file for important information like the database access credentials before it loads. And because WP-CLI doesn’t want to load WordPress, it uses regular expressions to strip the require_once(ABSPATH . ‘wp-settings.php’); statement.

If you’ve modified the wp-config.php file to call WordPress functions, you’ll see the “Call to undefined function” error. This occurs because PHP fails to call the WordPress function. Removing all WordPress functions from the configuration file should fix it.

You should avoid using the wp-config.php file to call functions. It’s better to move those modifications to a must-use plugin so WP-CLI can parse the config file without errors.

4. WP-CLI Doesn’t Load With the WordPress Install

Although rare, sometimes you might find that WP-CLI doesn’t load with your WordPress install. This is often caused by a theme or plugin that conflicts with the load process.

If you find that WP-CLI doesn’t load despite your best efforts, you can load it without loading themes and plugins using the following command:

 

$ wp --skip-plugins --skip-themes

If WP-CLI loads after this, you can find the conflicting theme or plugin by running the command using only one of the two arguments. For example:

 

$ wp --skip-themes

If WP-CLI loads after this, you’ll know the active theme is the problem. And if it doesn’t, you can try to load WP-CLI while skipping one plugin at a time as follows:

 

$ wp --skip-plugins=hello

Once you’ve identified the conflicting plugin, you can deactivate or uninstall it.

Managing Your WordPress Websites With WP-CLI

WP-CLI is a powerhouse of infinite possibilities. Whether you’re a first-time user or a seasoned marketer, WP-CLI ensures you can manage WordPress websites effortlessly. Use the tips above to get started, and continue to explore all of the commands available with this handy WordPress function.