What is the WP-CLI and why should I use it?

What is the WP-CLI?

The WP-CLI is a way of doing anything that you would be able to do in the back-end of a WordPress site in wp-admin, but using command lines. A number of hosts have WP-CLI installed on new servers. One great example is on Cloudways.

Common WP-CLI commands

If a client site has a white screen issues from an active plugin or theme and you have sFTP/SSH access on the site, then you can change the active plugins. You can also change the site to a new theme, or install a new default theme to test if the issue is an active plugin or active theme-related.

If you wanted to find out what plugins are active and you can not login on wp-admin on the site, you can run:

wp plugin list

This command will list all the plugins, and show which ones are active or not.

If you have an idea of which plugin could be causing the issue on the site, you can deactivate it using:

wp plugin deactivate

If you know the plugin you want to deactivate, then you can run

wp plugin deactive contact-form-7

so the plugin name would be the slug that is shown when you view the plugin on the WordPress.org page.

If you want to deactivate all plugins for a short while, then you can run:

wp plugin deactivate --all

Now that you have deactivated all plugins on the site, you should be able to login into the wp-admin on the site, and the website ought to be loading, or at least not whitescreening.

What if an active plugin needs to be rolled back to a previous version?

Well, that is easily possible using WP-CLI. In this example for Contact Form 7, we will set the version before the current one and then force the install.

wp plugin install contact-form-7 --version=5.0.3 --force

What about themes management?

If you wanted to test if the active theme was causing the issue, then you could use:

wp theme list

In this example, we want to set one of the default WordPress themes as the active theme, so we would run:

wp theme activate twentyseventeen

If you wanted to install and activate a new theme to test it, use:

wp theme install astra --activate

The theme name would be the slug as found on the WordPress.org. In this case, it was installing and then activating the Astra theme.

What if you wanted to create a backup of the site database using WP-CLI?

But a plugin that you are using to create a database backup, was timing out. The WP-CLI command to do so would be:

wp db export

The database would be exported to a filesname.sql file. So what if that backup file was from a 5-10GB database, the file is large, and you want to quick compress it so that the file is smaller to download and pull down to your computer? Well, that is where gzip would come in. You can decompress Gzip files very easily on a Mac or a PC. Now you went from trying to download a large SQL file, to one that might be 100-150MB in size.

gzip filename.sql

You would need to check in your preferred sFTP/SSH program in which you normally use the exported SQL file name.

The file would be written into the HTML folder on your client server, as WP-CLI has to be run from the folder where WordPress is installed. Otherwise, it would show as not having a valid WordPress install when trying to run any of the WP-CLI commands. After you have downloaded the database backup file, remember to delete the file from the HTML folder, or that file could be downloaded by anyone who finds the link.

If you needed to copy the database backup file to another server, you could use

wget

which is a very handy software package.

wget https://example.com/filesname.sql.gz

You could copy the file server to server, which always going to be faster than having to download the file, and then upload it to another server.

Mac and Windows have loads of solid options with a GUI for the sFTP/SSH clients. I like using WinSCP for a client with a GUI, and then have Putty for anything needing a terminal. It is very easy to setup WinSCP with Putty. Macs already have a great terminal built in for being able to login and run command line.

But what if you have a client site that is either going to change the domain name or a site that wanted to update from being HTTP to HTTPS? If you did not want to have to run another plugin like Really Simple SSL, which can be a mess to deal with if you change domains or create a staging site from that site later on.

Supported WP-CLI Search & Replace options

wp search-replace

wp search-replace ‘https://example.com’ ‘https://example.com’ --recurse-objects --skip-columns=user_email,guid --all-tables --dry-run

This command would change the site domain in the database from being HTTP to HTTPS, but is a dry run so will run the search and replace, but no changes will be made to the database.

wp search-replace ‘https://example.com’ ‘https://example.com’ --recurse-objects --skip-columns=user_email,guid --all-tables

This command would change the site domain in the database from being HTTP to HTTPS.

wp search-replace ‘https://example.com’ ‘https://domain.com’ --recurse-objects --skip-columns=user_email,guid --all-tables

This command would change the site domain in the database from being example.com to domain.com, and the site was already HTTPS.

This will replace all references in the site database, will skip GUIDs and user email, which in this case if you were changing a site domain name, you would not want to replace the email addresses in the site database.

Have used this method on very large site databases all the way up to 25GB, on those larger site database sizes, the search and replace might take a while to run, but it will complete.

After running the search and replace and say Redis was active on that site for object caching, then you would need to also run these two commands:

wp cache flush

wp rewrite flush

This command would flush the rewrite rules, which are the site permalinks. If you are changing from one domain to another or a site from HTTP to HTTPS without doing this, the site links on the site will show as being broken.

Why would I want to delete expired transients?

Transients are a storage cache method used in WordPress, but some of these values end up bloating the options database table. Expired transients do not get deleted all of the time by plugins setting those values to be retrieved. One example would be on a site using WooCommerce for e-commerce; the site has a high number of orders on it, and transients will build up over time. To delete expired transients in WP-CLI, you can run:

wp transient delete --expired

If you also have object caching active on that site, those transients would be stored in the object cache, so you will need to run the wp cache flush command, as well.

If you did need to delete all site transients, you can run this command:

wp transient delete --all

What if I could easily update an option value on my site?

In this example, you installed the Classic Editor on a client site, but you wanted to easily update the option value it uses. The default would be changed to replace Gutenberg with the classic editor.

wp option update classic-editor-replace replace --skip-themes --skip-plugins

What if I could easily delete all of the spam comments on a site?

In this example, all spam comments will be deleted on the site.

wp comment delete $(wp comment list --status=spam --format=ids)

What else can WP-CLI be used for?

Well, loads of plugins with do support WP-CLI. A select few that come to mind would be:

• WooCommerce,
• Gravity Forms,
• WP Migrate DB Pro,
• EWWW Image Optimizer,
• Beaver Builder,
• Elementor
• and MainWP.

Also, a whole range of WordPress plugins offer WP-CLI support.

How can WP-CLI be used for MainWP?

MainWP included WP-CLI with these very handy commands, so if you wanted to sync all connected child sites to the MainWP Dashboard site use: 


wp mainwp sites --sync-sites 

You have synced the child sites and now want to list the plugins showing updates, then upgrade those plugins:

wp mainwp updates --available-updates 

Then you would run:

wp mainwp site --site-update-plugins <id> 

We have covered why to use WP-CLI on client sites, to speed up common tasks on those sites, which plugins support WP-CLI and which commands MainWP supports for WP-CLI. The strongest part of WP-CLI is that each release has solid changes being made. Also, we have not covered awesome commands like wp profile, wp doctor, as well as the many packages for WP-CLI, there are so many other WP-CLI commands that could have been covered as well.

All of the WP-CLI commands mentioned in this post and a few others are in shown in this Gist.

I hope that getting used to using WP-CLI, is not as hard or as complex as it seems, the commands when used all of the time, will become second nature.