The WordPress command line interface (WP-CLI) is a powerful WordPress-developer focused tool. Here at Delicious Brains we use it to help us write tests, manage changes to our site databases, and we even have WP-CLI support in WP Migrate DB Pro. Last but not least, SpinupWP, our cloud based server control panel for WordPress, makes heavy use of WP-CLI to manage WordPress sites, so it is an incredibly important tool for us.
We love it so much, we think it’s important that every WordPress developer knows how to install and use it. This post will cover installing WP-CLI and setting it up to work efficiently with this amazing tool.
Table of Contents
- What Is WP-CLI?
- How to Install WP-CLI on macOS and Linux
- How to Install WP-CLI on Windows
- After Installing WP-CLI
- Wrapping Up
What Is WP-CLI?
WP-CLI is a command line interface for WordPress. It allows you to do many of the same tasks as the administration panel on your WordPress site, but from a command line terminal on your computer or a web server. This makes it very useful both during development and once the site is deployed. You can use WP-CLI to install WordPress, configure multisite installations, update plugins and themes, update WordPress itself, and much more.
Once you feel comfortable with WP-CLI, you will find this is often quicker than doing the same thing via the web browser (and it makes you look really cool while doing it).
Command line tools like WP-CLI are also great for repetitive tasks, like adding users in bulk or checking for updates on a regular basis. This is because WP-CLI is easy to combine with other command line tools and utilities like Bash scripts and cron jobs.
People use WP-CLI for a wide variety of WordPress related tasks. For example…
Installing and activating a plugin:
$ wp plugin --activate advanced-custom-fields
Adding a user:
$ wp user create erik [email protected] --role=subscriber
Updating WordPress core and the database:
$ wp core update && wp core update-db
Taking a snapshot of the database:
$ wp db export /mnt/backups/$(date +%Y%m%d).sql
Adding a single user, running one-off backups, or performing update checks using the command line might not be a big win over using the administration pages. However, if you have 500 users to add, or want to get updates and backups done at 3 a.m. every morning, having a command line tool becomes really handy.
We’ll go in-depth on how to get the most out of WP-CLI in a future tutorial, including hints, tips, and tricks that the Delicious Brains team have picked up over the years. But first things first, let’s get WP-CLI properly installed.
How to Install WP-CLI
These instructions are for Mac and Linux users. Click here to jump to the instructions for installing on Windows.
The Official Method
The recommended way to install WP-CLI is documented on the WP-CLI site. Installing WP-CLI on a Mac or Linux machine requires PHP version 5.6 or later and you must have the cURL command line tool installed. Open your terminal and run the following commands.
The first step is to download the Phar build:
$ curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
Next, you need to verify the downloaded file:
$ php wp-cli.phar --info
Finally, make it executable and move it into your PATH:
$ chmod +x wp-cli.phar
$ sudo mv wp-cli.phar /usr/local/bin/wp
Installing WP-CLI Using a Package Manager
The WP-CLI developers are not actively involved in maintaining packages for the multitude of package managers. The options for installing WP-CLI using a package manager vary depending on which package manager you use and if any volunteers have stepped in and created a package for it.
Installing WP-CLI Using APT
Tiago Hillebrandt maintains a PPA for installing WP-CLI on Debian/Ubuntu and all its variations. You can use his PPA like this:
$ sudo add-apt-repository ppa:tiagohillebrandt/wp-cli
$ sudo apt-get update
$ sudo apt-get install wp-cli
Installing WP-CLI Using Homebrew
Homebrew has a formula for WP-CLI, so it’s a matter of running the following command:
$ brew install wp-cli
Installing WP-CLI Using Composer
You can also use Composer to install WP-CLI. While the most common use for Composer is to maintain dependencies inside your PHP project, it can also be used to install tools on your machine. It’s possible to install WP-CLI just for your current project if you absolutely need to have a specific WP-CLI version. It is quite rare that a project needs anything other than the latest version, so my recommendation is to install it globally. It’s nice to have WP-CLI easily accessible everywhere and it’s one less dev dependency in my projects. Here’s how to install it globally:
$ composer global require wp-cli/wp-cli
This installation method requires you to add ~/.composer/vendor/bin to your PATH variable. This works differently depending on whether you’re using MacOS, Linux, or Windows. Here are some useful links for using Bash or Zsh.
Once you have installed WP-CLI globally like this, you can reach it from any folder on your computer.
Installing WP-CLI via Docker
The Docker community maintains WordPress and WP-CLI images. You can use the WP-CLI image in your Docker projects by specifying the CLI variant as your WordPress image in the yml file created by docker compose.
image: wordpress:cli
Verifying That WP-CLI Works
Regardless of which installation method you use, it’s a good idea to verify that the installation succeeded and WP-CLI is accessible regardless of which directory you happen to be in. To verify that things work as they should, you can pass the --info parameter:
$ wp --info
If it’s installed correctly, you should see something like this:
OS: Darwin 20.6.0 Darwin Kernel Version 20.6.0: Wed Nov 10 22:23:07 PST 2021; root:xnu-7195.141.14~1/RELEASE_X86_64 x86_64 Shell: /bin/zsh PHP binary: /usr/local/Cellar/[email protected]/7.4.27/bin/php PHP version: 7.4.27 php.ini used: /usr/local/etc/php/7.4/php.ini MySQL binary: /usr/local/bin/mysql MySQL version: mysql Ver 8.0.28 for macos11.6 on x86_64 (Homebrew) SQL modes: 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: /usr/local/bin WP-CLI packages dir: WP-CLI global config: WP-CLI project config: WP-CLI version: 2.6.0
How to Install WP-CLI on Windows
Installing WP-CLI on native Windows is slightly different from installing it on a Mac or Linux machine. Before we start, using the Windows Subsystem for Linux that Microsoft introduced a few years ago you should be able to install using the instructions for MacOS and Linux above. If you want it working under native Windows the following steps are for you.
Please be aware that WP-CLI is first and foremost made for *nix based systems. Some functionality, like accessing remote WordPress sites via SSH, may require you to jump through quite a few hoops. Other features may not work at all. But getting a basic installation of WP-CLI up and running on a Windows machine is possible.
Note that your Windows user account must have administrator rights for these steps to work. If you don’t have administrator rights, then you need to ask someone that does to either give you administrator rights or help you out with these steps.
Windows Requirements
To get started with installing the WordPress command line on Windows, the only real requirements are that you have command line PHP for Windows installed and added to your PATH so that you can run PHP from the command line in any working directory. The easiest way to install WP-CLI is by using cURL. Most Windows installations already have cURL installed, as it’s been included with Windows 10 since 2018.
Today we celebrate that Windows 10 has shipped curl bundled with the OS for exactly 4 years.
— Daniel 🥌 Stenberg (@bagder) March 1, 2022
If you don’t already have it on your machine I highly recommend you install it using one of these suggested methods or by downloading it from the cURL home page before continuing.
Download and Install
First you need to download the latest build of the wp-cli.phar from GitHub into a local folder. If you have cURL installed you can do this with three commands:
C:\> mkdir C:\wp-cli
C:\> cd C:\wp-cli
C:\> curl -O https://raw.github.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
If you don’t have cURL and can’t install it, you can also create the C:\wp-cli folder in your Windows File Explorer manually, download the file using the link above, and then move it to that folder.
After downloading the file, it’s a good idea to confirm it works by typing:
C:> php C:\wp-cli\wp-cli.phar --info
You should see a couple of lines summarizing your local WP-CLI environment.
Typing the full path to the phar file every time you run a WP-CLI command is going to get old really fast. So to make life a little easier, we are going to do two more steps. First we permanently add the C:\wp-cli folder to the PATH environment variable. I prefer to do this using the setx command. You can select between adding it to just your environment or adding it for all users by using the /m switch.
For all future sessions with your user account:
setx PATH "%PATH%;c:\wp-cli"
For just the current terminal session:
set PATH "%PATH%;c:\wp-cli"
Or for all future sessions, for all users on the system:
setx PATH "%PATH%;c:\wp-cli" /m
Just adding the path to your own environment is fine if this is your local development machine. If it is a server where you will potentially schedule nightly jobs using WP-CLI, it’s better to add it to the environment for all users. Using setx with the /m switch requires you to open a CMD terminal with full administrative rights. The easiest way to do that is to search for cmd.exe on the Start menu, right click it, and select Run as administrator to open it:
Finally, we create a windows batch file in the WP-CLI folder named wp.bat with the following content:
@ECHO OFF
php "c:\wp-cli\wp-cli.phar" %*
This .bat file will enable you to call run WP-CLI using the shorter wp instead of always typing the full name of the phar file. It saves you a bunch of typing and it is also how WP-CLI is called on Mac and Linux.
Verifying That WP-CLI Works on Windows
With all of the above in place, we should now be able to run WP-CLI from any folder:
C:\> wp --info
If it’s installed correctly, you should see something like this:
OS: Windows NT 10.0 build 19043 (Windows 10) AMD64 Shell: C:\WINDOWS\system32\cmd.exe PHP binary: C:\php\php.exe PHP version: 7.4.27 php.ini used: MySQL binary: MySQL version: SQL modes: 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: C:\wp-cli WP-CLI packages dir: WP-CLI global config: WP-CLI project config: WP-CLI version: 2.6.0
After Installing WP-CLI
Once you have WP-CLI up and running and have verified that it works, it’s time for some initial setup. One of the core concepts of WP-CLI is commands that can have subcommands. Each of these commands and subcommands can have a bunch of optional switches. You can sometimes end up typing pretty long command strings. Just the other day I needed to insert an array element inside a WordPress option and the command ended up like this:
$ wp --path=www/testing option patch insert tantan_wordpress_s3 post_meta_version 7
Once you get comfortable with WP-CLI, you will no doubt learn a lot of these commands by heart. But if this looks like more typing than you like to do on a regular basis, let me show you some things you can do to make it feel less daunting and a lot more likely to be correct on the first attempt.
Setting Up Tab Completion
The first thing we’re going to do is enable tab completion, which is the mechanism in the shell that automatically suggests what you should type next when you hit the TAB key. In my environment, I just type the start of that command above to see which subcommands there are:
$ wp option [TAB]
add delete get list patch pluck update
Setting up tab completion is too easy to not do it, but it helps to know which command line shell you are using. If you’re not sure, let me quickly show you how to do that by checking the $SHELL environment variable:
# On older MacOS and on most Linux boxes, we should see /bin/bash
$ echo $SHELL
/bin/bash
# On newer MacOS boxes, we should see /bin/zsh
$ echo $SHELL
/bin/zsh
# Check for Oh My Zsh
$ omz
Usage: omz <command> [options]
Available commands:
help Print this help message
changelog Print the changelog
plugin <command> Manage plugins
pr <command> Manage Oh My Zsh Pull Requests
reload Reload the current zsh session
theme <command> Manage themes
update Update Oh My Zsh
version Show the version
If you are using Oh My Zsh this is the easiest thing ever. Just type the following command:
$ omz plugin enable wp-cli
omz::plugin::enable: plugins enabled: wp-cli.
If you are using straight Bash or Zsh, there are just a few more steps involved to download the script and add it to your environment. First, switch to your home folder and download the script for version 2.6.0 of WP-CLI:
$ cd ~/
$ curl -O https://raw.githubusercontent.com/wp-cli/wp-cli/v2.6.0/utils/wp-completion.bash
Next, add it to your profile and reload. Bash users can use these commands:
$ echo "source ~/wp-completion.bash" >> ~/.bash_profile
$ source ~/.bash_profile
Zsh users, however, should use these:
$ echo "source ~/wp-completion.bash" >> ~/.zshenv
$ source ~/.zshenv
On a Linux system, instead of sourcing wp-completion.bash from your ~/.bash_profile, you need to do so from your ~/.bashrc. Make sure the wp-completion.bash file is in your home directory, then run the following commands from the home directory:
cat wp-completion.bash >> .bashrc
source .bashrc
While tab completion to some extent also exists for Windows, to the best of my knowledge it’s not possible to integrate it with third-party tools such as WP-CLI like it is on Mac or Linux. If you know a way to add WP-CLI tab completion on Windows, please reach out in the comments below.
Creating a WP-CLI Configuration File
The next thing I always do as soon as I have a working WP-CLI installation is to add a configuration file to my $HOME folder. Configuration files are a fairly advanced topic with lots of interesting functionality that could warrant an entirely separate article. Getting a basic configuration file in place is a great way to reduce the amount of repetitive typing.
Without a configuration file in place, WP-CLI will assume that your working directory is the same as the wp-config.php file of the actual WordPress site. A lot of times you won’t be in that directory. For example, every time you open up your terminal, you will typically be in your $HOME folder. Luckily you can supply the --path parameter to WP-CLI to make it look in the correct folder:
$ wp --path=/Users/eriktorsner/src/path/to/wordpress plugin list
As you can imagine it quickly gets rather tedious to keep typing that initial path variable every single time. To reduce the amount of typing you can add a config file that WP-CLI will use to get path and other important parameters.
To create this file, open up your favorite text editor and create a file named wp-cli.yml in your home directory. Add the following line:
path: /Users/eriktorsner/src/path/to/wordpress
You need to adjust that path so it matches where you have—or are planning to put—your local WordPress installation. With this file in place, WP-CLI will automatically know where to look for the WordPress installation so you don’t have to type it every time.
Every time you run the WP-CLI command, it will look for a configuration file to use. There are several potential places to put a config file and there is a specific priority that determines which configuration file is chosen, from highest to lowest priority:
- A file named
wp-cli.local.ymlin the current working directory or upwards - A file named
wp-cli.ymlin the current working directory or upwards - A file named
wp-cli.ymlin your$HOMEfolder
Note that the “or upwards” means that, assuming you keep a config file in the root of your WordPress installation, WP-CLI will still be able to find if you have worked yourself down into a subdirectory such as wp-content/uploads/year/month. It’s also worth knowing that if you want to put your config file somewhere other than your home folder, you can always specify a location using the WP_CLI_CONFIG_PATHenvironment variable.
Any parameter you supply via the typed command will override values picked up from a config file, which makes it easy to override values from a config file when needed.
This section has just barely scratched the surface of how incredibly useful the WP-CLI configuration file can be. In a future post, I plan to dig in much deeper and show you how I use them to manage my local WordPress development environments.
Updating WP-CLI
WP-CLI has the ability to self update. If you installed WP-CLI using the recommended method, you can update it using the update sub command:
$ sudo wp cli update
On your local development environment, you may want to try out the latest and greatest features of WP-CLI and use the nightly build (but please avoid this on production servers):
$ sudo wp cli update --nightly
If you installed WP-CLI using a package manager, you should always update using the package managers mechanism instead. Updating directly will almost certainly work but I don’t recommend it. You would be robbing the package manager of its chance to know which version is currently installed. That’s never a good thing. Once you have selected your installation method, I suggest you stick with it for updates as well.
Wrapping Up
If you have followed along in this post, you should now have a working installation of WP-CLI set up with tab completion and a basic configuration file in place. We will start looking at actually getting work done with this tool by digging into plugin management in a future post.
In the meantime, you might want to read our article on WP-CLI packages we can’t live without, or our series on automating local WordPress site setup with scripts.
If you have any questions about how to install WP-CLI, don’t hesitate to let me know in the comments below.
