Getting started with WP-CLI today

WP-CLI v2 was released recently and here at 34SP.com, we’re big fans. For those that have never come across WP-CLI, it’s a command line tool for WordPress that makes managing sites a lot easier. How easy? Well, our apprentices’ first experience of managing a WordPress site is through WP-CLI before we even show them the normal WordPress admin interface.

To get started with WP-CLI you will need a couple of things: To be using our Managed WordPress or Universal Hosting with WordPress installed, and SSH access.

Getting SSH access is easy, follow the knowledge base steps for setting up an (S)FTP user. Unlock access by setting your SFTP lock to unlocked and connect via your terminal or a program like Putty.

Once logged into your server, you’re ready to use WP-CLI so let’s start with a very simple command, “wp plugin list”.  This will return a list of plugins and some basic information like if they are active, if they need an update, and their version.

wp plugin list
+---------------------------------------+----------+--------+------------------+
| name                                  | status   | update | version          |
+---------------------------------------+----------+--------+------------------+
| akismet                               | active   | none   | 4.0.8            |
| gutenberg                             | inactive | none   | 3.4.0            |
| tfsp_tools                            | active   | none   | 2.1.13           |
| wp-fingerprint                        | active   | none   | 1.0.1            |
| wp-notification-center                | active   | none   | 1.0.1            |
| wordpress-seo                         | active   | none   | 7.9.1            |
| advanced-cache.php                    | dropin   | none   |                  |
| object-cache.php                      | dropin   | none   |                  |
+---------------------------------------+----------+--------+------------------+

Most WP-CLI commands take the form of “wp” “command” “action” “parameters” “arguments” and always start by using “wp” to tell the server you wish to use the WP-CLI command.

In our original example, we had a command of “plugin” and the action of “list”, so we are asking the plugin command to list our plugins. Let’s add an “argument”.  Arguments use “–” at the start of each, and unlike command and actions, we can have multiple arguments.

wp plugin list --status=inactive
+----------------------+----------+--------+---------+
| name                 | status   | update | version |
+----------------------+----------+--------+---------+
| gutenberg            | inactive | none   | 3.4.0   |
+----------------------+----------+--------+---------+

In our new example, we are saying filter the list by status looking only for plugins that are inactive.

Let’s try a new command and make the Gutenberg plugin active by running “wp plugin activate gutenberg”.

wp plugin activate gutenberg
Plugin 'gutenberg' activated.
Success: Activated 1 of 1 plugins.

This time we passed the parameter of “gutenberg” to our action of “activate” which is an action of the command “plugin”. Like arguments, we can have multiple parameters, though not all actions have parameters and if we put in a parameter that it’s not expecting we’ll end up with an error.

In our example we activated Gutenberg, but we can also deactivate a plugin from the command line. This is particularly useful if your site has an error such as the infamous “white screen of death” and you can’t log in to your dashboard. If we know the plugin causing the error (gutenberg, in this example) we can run “wp plugin deactivate gutenberg –skip-plugins”.

wp plugin deactivate gutenberg --skip-plugins
Plugin 'gutenberg' deactivated.
Success: Deactivated 1 of 1 plugins.

Notice the “–skip-plugins” parameter; this tells WP-CLI to run, but not to load any WordPress plugin code. If we don’t do this, then we might get the same fatal error as the frontend of our site. We can also use “–skip-themes” if we think the theme is likely to cause problems.

Out of the box WP-CLI has lots of commands we can use, from manipulating plugins, to users, to changing settings.

Here at 34SP.com, one of the commands we use every day is the search and replace function, indeed this was the main reason we as a company started using WP-CLI. This command allows you to switch URLs or indeed anything within the database.  For example:

wp search-replace 'http://example.com' 'https://example.com' --dry-run

This would find all references of http://example.com and replace it with https://example.com. This includes changes inside serialised arrays, something that would normally be pretty tricky even in mysql directly. The “–dry-run” parameter indicates that it should just report the changes it’s about to make rather than making them, so it brings back a list:

| wp_postmeta        | meta_key              | 0            | SQL  |
| wp_postmeta        | meta_value            | 0            | PHP  |
| wp_posts           | post_content          | 18           | SQL  |

If you’re happy with the changes that are about to be made, you can remove the “–dry-run” parameter and run it for real.

This has just been a small taste of the types of commands you can run in WP-CLI. Combined with other unix shell commands, you may never have to log in to your WordPress admin dashboard again!

If this has piqued your interest, last year our WordPress and Systems Specialist Keith Hyde and myself took over WordPress Bristol for the evening to talk all things WP-CLI, from the very basics through to more advanced topics.

Within our arsenal of tools, WP-CLI is the one that our WordPress Specialists rely on, be it for looking at what plugins are installed, removing and deactivating plugins through to more sophisticated tasks like looking at cron events that should be run.

If you have never used the command line, and we appreciate it can be a daunting prospect, we strongly recommend giving it a try. WP-CLI is available on both our WordPress Hosting and Universal Hosting out of the box. Just navigate to a folder with WordPress in and type “wp” to get started.