How to install and configure WP-CLI

Last updated: 9 March 2022

WP-CLI is a great framework for anyone who uses WordPress and is familiar with the Linux command line. As the name suggests, WP-CLI gives you a command-line interface for WordPress. Pretty much every admin task you can perform via the WordPress dashboard can be done right from the command line.

This article covers how to install and configure WP-CLI. If you already have installed the utility then you can skip to one of our other WP-CLI articles:

• Installing WordPress using WP-CLI
• Managing WordPress options via WP-CLI
• Managing plugins and themes via WP-CLI

Installation

For this article I will install WP-CLI for the domain example.com. The site lives on our cpweb6 server, which is one of our Premium servers. That means that everything we need to install WP-CLI is available: we got SSH access and PHP’s Phar extension is enabled out of the box.

There are a couple of things you need to do to install WP-CLI:

• Download the wp-cli.phar file
• Store the file in a directory for executable files
• Rename the file to wp
• Make the file executable

Not all these steps are required. For instance, you don’t need to rename the executable to wp. However, it is common practice to do so, and all example commands in the excellent WP-CLI handbook use wp as the name of the executable.

Download, rename, make executable

The executable should be installed in a directory in your PATH. In most cases that is the ~/bin directory. You may need to create the directory first:

[example@cpweb6-premium ~]$ mkdir ~/bin

Next, you can change to the bin directory and download the wp-cli.phar file. I am using curl with the -o option to rename the file to wp at the same time.

[example@cpweb6-premium ~]$ cd ~/bin
[example@cpweb6-premium bin]$ curl -o wp https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

And finally, you need to make the file executable:

[example@cpweb6-premium bin]$ chmod +x wp

The first test

To check if everything works correctly you can navigate to the public_html directory and execute the command wp --info. The command outputs basic information about the server, shell, PHP and WP-CLI.

[example@cpweb6-premium bin]$ $ cd ; pwd
/home/example

[example@cpweb6-premium ~]$ wp --info
OS:	Linux 3.10.0-962.3.2.lve1.5.28.el7.x86_64 #1 SMP Tue Jan 28 04:53:14 EST 2020 x86_64
Shell:	/bin/bash
PHP binary:	/opt/cpanel/ea-php72/root/usr/bin/php.cagefs
PHP version:	7.2.27
php.ini used:	/opt/cpanel/ea-php72/root/etc/php.ini
WP-CLI root dir:	phar://wp-cli.phar/vendor/wp-cli/wp-cli
WP-CLI vendor dir:	phar://wp-cli.phar/vendor
WP_CLI phar path:	/home/example
WP-CLI packages dir:	
WP-CLI global config:	
WP-CLI project config:	
WP-CLI version:	2.4.0

Adding tab completion

Every proper shell supports tab completion, and you can download a small script that makes tab completion work for WP-CLI. If you don’t know what tab completion is, it allows you to let the shell complete a command when you hit the Tab key. For instance, if you want to run the command wp plugin list you can start typing wp pl and press the Tab key – it will then automatically complete pl to plugin. When a string can’t be completed because there is more than one possible match then you can hit the Tab key a second time, and the shell will show you all available options.

I will download the script to my home directory (as I don’t really want it in the public_html directory):

[example@cpweb6-premium]$ cd ~ && wget https://raw.githubusercontent.com/wp-cli/wp-cli/v2.6.0/utils/wp-completion.bash

Next, we need to tell Bash to “source” the file. That way, the tab completion script is available every time a new shell session starts.

[example@cpweb6-premium]$ echo "source /home/$USER/wp-completion.bash" >> ~/.bash_profile 

And, finally, we need to reload our .bash_profile file:

[example@cpweb6-premium]$ source ~/.bash_profile

Install script

We use WP-CLI quite a bit. To make the installation process a bit quicker we have written a Bash script that does all the above with a single command. The script also has an option to uninstall WP-CLI.

If you manage a server with lots of users and WordPress installs, you should be aware that WP-CLI should not be run as root. Instead, you should always install the utility as a less privileged users, and all WP-CLI commands should be run as that user as well.

PHP errors

On cPanel servers WP-CLI uses the default PHP version. You are likely to encounter errors if that version is a legacy version, such as PHP 5.6. If the WordPress install uses a newer version, such as PHP 8.1, then it is very likely that any command you run triggers an error. There are no easy work-arounds for that. The best solution is to change the inherited PHP version to a version that is current.

Updating WP-CLI

WP-CLI is free and open source software, and it is actively developed. That means there are regular updates that fix bugs and improve WP-CLI’s functionality. It is important to update WP-CLI regularly, and of course you can do so via WP-CLI itself:

$ wp cli update
Success: WP-CLI is at the latest version.

Where to go from here?

You can now start using WP-CLI. If you are new to WP-CLI then the articles about installing WordPress and managing WordPress options and plugins/themes will make you more familiar with the utility. And, of course, bookmark the official WP-CLI Commands page.