WP-CLI is a command line tool for developers to manage common tasks (and not so common) of a WordPress installation. It can add/remove users, posts, categories, insert test data, search and replace in the database, help troubleshoot performance issues, and much more!

WP-CLI has been an open source project for over a decade, being maintained primarily by Daniel Bachhuber since 2003. The primary goal of WP-CLI is to help speed up WordPress developer’s workflows.

Over the years the project has emerged into so much more! It’s now even becoming a requirement for other open source projects such as Trellis and Bedrock. As of January 2017, WP-CLI officially moved to WordPress.org and is also now being maintained co-maintained by Alain Schlesser.

WP-CLI v2 was released on August 8th, 2018, so we’ll also explore some of the changes and new features. If you’re a Host SEO client, WP-CLI v2.0.1 is installed by default on all of our servers, simply SSH into your server to get started. SSH access is included in all of our hosting plans.

• Getting WP-CLI
• The Basics Of WP-CLI
• WP-CLI Commands in General
• Useful Examples
• Using WP-CLI Remotely
• Using Bash Scripts

Getting WP-CLI

The minimum PHP requirement on WP-CLI v2.0.0 has been bumped up to PHP 5.4. While this is a good move ahead, we recommend that you at least run a supported version of PHP, meaning 5.6 or higher. PHP 7.2 is default on all Host SEO installs, both for security and performance reasons. We also have PHP 7.3 available.

To get started you’ll need to install WP-CLI – a very simple process. The steps for Linux and OSX are the following, issue these three commands one after the other:

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp

If something goes wrong or you are on Windows refer to the basic instructions or the alternative installation methods.

Once done you should be able to issue the wp --info command and get a meaningful response.

The process is the same if you want to install WP-CLI on your server. Remember, for Host SEO clients WP-CLI is already installed. Not sure which version you’re currently running? You can always issue the wp cli version command to find out.

The Basics Of WP-CLI

Having access to WordPress from the command line is powerful in and of itself but can give you even more control and speed gains when using bash scripts.

Bash scripts allow you to run a sequence of commands with a single command. You could type bash install-and-setup.sh and get the following result:

• Download WordPress
• Create and populate wp-config.php
• Create the database
• Install WordPress
• Install and activate any plugins you need
• Install and activate a theme
• Download and add test content

These would be the steps I would take to create a new test environment for a project. Normally it would take me 5-10 minutes at least, especially if there are a few plugins involved. Issuing a single command is obviously a lot faster.

WP-CLI Commands in General

If you are used to working in the terminal there’s nothing special about WP-CLI for you. Commands always start with wp followed by a command and subcommand, followed by required and optional parameters, something like this:

wp command subcommand requiredparam --optionalparam --optionalparam2=value

Let’s install a theme to see how this works with a real command:

wp theme install twentyseventeen --activate

This will install and activate the Twenty Seventeen theme on your WordPress installation.

Note that WP-CLI will work with the WordPress installation you are currently in the terminal. If you switch directories to go to another WordPress installation, it will work with that one.

Useful Examples

That was WP-CLI in a nutshell! While there are a few advanced things you can do, which we’ll get to in a moment, you already know enough to get started and do whatever you need to. I recommend taking a look at the commands list, try some of them out. We’ll take a look at some useful stuff here, then move on to using WP-CLI over SSH and using bash scripts.

Installing WordPress

I use WP-CLI a lot to set up test environments, the first step of which is a vanilla installation. Here is a list of commands I run:

wp core download
wp core config --dbname=mydbname --dbuser=mydbuser --dbpass=mydbpass --dbhost=localhost --dbprefix=whebfubwef_ --extra-php <<PHP
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
PHP
wp db create
wp core install --url=http://siteurl.com --title=SiteTitle --admin_user=username --admin_password=mypassword --admin_email=my@email.com

Note how cool this is! The most recent version of WordPress is downloaded using the first command. The second command sets up the config file with the database access and some additional PHP at the end. The additional constants make sure we have our debugging options on for testing.

The third command creates the database (WP-CLI uses the database access info from the config file) and finally, we install WordPress using a couple of parameters.

Reinstall WordPress Core

You can also reinstall WordPress core using WP-CLI. The following command would download WordPress core without the default themes and plugins.

wp core download --skip-content --force

Change WordPress URL

There are many reasons why you might need or want to change your WordPress URL. Perhaps you are changing domains, moving to a subdomain, updating from www to non-www, moving files around, or even migrating from HTTP to HTTPS. Whatever the case may be, you can use easily use the wp option update command for this. Here is an example below:

wp option update home 'http://example.com'
wp option update siteurl 'http://example.com'

List of Current Plugins with Details

To get a list of current plugins installed on a site simply use the following command. In this example, you can see we have the Schema and Yoast SEO plugin installed. It will also return the status (active/deactivated), if there is an update available, and the current version.

wp plugin list

Installing Multiple Plugins

To install multiple plugins you can simply pile on parameters. Here’s an example that downloads and activates 3 plugins:

wp plugin install advanced-custom-fields jetpack ninja-forms --activate

Note that the plugin names come from their name in the repository. The easiest way to figure this out is to visit their page and look at the URL or to use wp plugin search searchterm which will give you a list in the terminal.

You can also install older versions of WordPress plugins if needed with the --version attribute.

wp plugin install wordpress-seo --version=4.8 --activate

Even cooler, you can install plugins from remote files, not just the repository which is handy if you’re developing a plugin, or using a premium plugin. The following command installs two plugins from the repository and one from an Amazon S3 server.

wp plugin install advanced-custom-fields jetpack https://d1qas1txbec8n.cloudfront.net/wp-content/uploads/2015/06/23073607/myplugin.zip --activate

Deactivate Multiple Plugins

To deactivate a single plugin you can run the following command.

wp plugin deactivate wordpress-seo

To deactivate all your plugins at once run the following command.

wp plugin deactivate --all

This above command can be handy if you’re troubleshooting compatibility issues and simply need to deactivate all the plugins in one fell swoop. You can then go back and enable them one by one, testing as you go.

Update Plugins

You can also manually update WordPress plugins. Example below:

wp plugin update wordpress-seo

Database Search And Replace

One of the main reasons it is difficult to migrate a site by just copy-pasting a database is that the database contains serialized arrays. If you need to replace all instances of http://testsite.com with http://livewebsite.com your serialized arrays will not make sense because the string count won’t match up.

The search-replace command unserializes arrays first, then performs the search and replace, then re-serializes the arrays. You can get this done with a simple command:

wp search-replace oldstring newstring

Additional parameters allow you to do a lot more, including preview what will be replaced by using --dry-run.

Import And Export

There are two ways to export content with WP-CLI. You can create an XML file, just like the WordPress export tool does, or you can export/import the raw database. I find the later a lot more useful in my daily routine, it comes in handy when syncing sites.

wp db export is all you need to do to create a SQL file and wp db import file.sql is all you need to import it. Works like a charm, just be careful not to overwrite anything you need, importing will basically dump the existing database and use the supplied SQL file instead.

Manage Roles And Capabilities

WP-CLI can manage roles for you pretty easily using the wp role command. This is pretty cool if you want to test how your plugin works with custom roles but you don’t actually create the roles within your plugin.

wp role create organizer Organizer
wp cap list 'editor' | xargs wp cap add 'organizer'
wp cap add 'organizer' 'manage-events'

The commands above will create a new role (Organizer), add all capabilities from the editor role to it and then add a new capability: manage-events.

Generate Test Data

I love all sort of faker-like functions – ones that add dummy content to your site that you can use for tests. WP-CLI has a couple of these built in, here are a few functions that will generate users, terms and posts.

wp user generate --count=5 --role=editor
wp user generate --count=10 --role=author
wp term generate --count=12
wp post generate --count=50

Manage WP-Cron Events

You can manage WP-Cron events and or a WordPress Cron job in WP-CLI. For example, the following command will give you your current cron event list.

wp cron event list

Delete Transients

You can even delete and clear out one or all transients using the following command.

Clean up wp_options Table

The wp_options table can be a common culprit for slow query times on your site due to autoloaded data that is left behind from third-party plugins and themes. Check out this great article from WP Bullet on how to use WP-CLI to clean up your wp_options table.

Delete WordPress Revisions

On large sites, WordPress revisions can add up very quickly to thousands of rows in your database which are not needed. You can delete post revisions with WP-CLI. Here is an example of the command:

$ wp post delete $(wp post list --post_type='revision' --format=ids)

wp maintenance-mode activate
wp maintenance-mode deactivate
wp maintenance-mode status

wp i18n make-pot <source> [<destination>] [--slug=<slug>] [--domain=<domain>] [--ignore-domain] [--merge[=<file>]] [--exclude=<paths>] [--skip-js]

ssh:

  staging:
    cmd: ssh %pseudotty% username@server.com %cmd%
    url: http://myseite.com
    path: /www/path/to/site/root

wp ssh core update --host=staging

wp core download
wp core config --dbname=mydbname --dbuser=mydbuser --dbpass=mydbpass --dbhost=localhost --dbprefix=whebfubwef_ --extra-php <<PHP
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
PHP
wp db create
wp core install --url=http://siteurl.com --title=SiteTitle --admin_user=username --admin_password=mypassword --admin_email=my@email.com

wp ssh core update --host=clientA
wp ssh core update --host=clientB
wp ssh core update --host=clientC
wp ssh core update --host=clientD