WP-CLI: what is it and how do you use it?

What is WP-CLI?

As the name suggests, it is a command line interface for WordPress, a console tool dedicated to WordPress. It lets you perform various administrative tasks from the command line, which in turn opens up possibilities for automation.

How do you use it?

First, we need to make sure WP-CLI is available in our development environment.

First, let’s download the archive to the local machine:

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

If everything went correctly, we should be able to run the command:

php wp-cli.phar --info

In the next step, let’s set the executable bit and move the library to the right place:

chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp

At this point we have everything we need for our fun.

What exactly can we do?

WP-CLI is very useful in many cases. It works best for routine tasks, which is also where it is used most often:

• installing plugins
• updating plugins and WordPress itself
• installing WordPress
• configuration
• managing users
• creating your own commands

Below I present a few selected scenarios that best demonstrate the capabilities of this tool.

WordPress from scratch: installing a clean instance

In a WordPress developer’s work, when a new project comes in, we have to spend a few moments preparing a fresh WP installation along with a few standard plugins we use most often. WP-CLI makes this process easier, keeping it to a minimum.

First we need to download the latest WordPress package. This command will help:

 

wp core download --locale=pl_PL

All tasks related to the WordPress engine of our application are preceded by the core command. In this case we also made sure the package was downloaded in the right language version.

Now it is time for the installation, but before we get there we need to create the configuration for our WordPress.

wp config create --dbname=db_test --dbuser=user_test --dbpass=test_pwd
wp core install --url=test.local.pl --title='A brand new website' --admin_user=admin_account --admin_email=admin@gmail.com

This way we created the wp-config.php configuration file and installed the application, providing all the necessary information about the new website’s address, its title and the administrator. As a result, the command prints the admin password of the new website to the screen.

Now we can move on to installing the plugins we cannot do without. A few commands are enough to download a plugin from the repository and then activate it.

wp plugin install wordfence
wp plugin activate wordfence

As you can probably guess, you can deactivate plugins in a similar way, which is a big advantage when trying to troubleshoot WordPress.

At this point we have a fully working fresh WordPress installation at our disposal. As you can see, with environment variables it is easy to prepare a script that would do the whole job automatically.

So let’s move smoothly on to the next scenario.

Managing users

It very often happens that someone loses the password to their WordPress account. The password reminder system usually comes to the rescue then. However, we cannot always use this option. The reason may be incorrectly configured email delivery, or a WAF system that has blocked us. In such a situation we have two options: either manually digging around in the database or using the console interface.

wp user update 1 --user_pass=zupelnienowehaslo123

This way we updated the password for the user with the ID equal to 1. But how do we know the ID of the user we want to give a new password? Another user-related command helps here, printing a list for us on the screen.

wp user list

If we do not want to change the password from above, we can also start the password recovery procedure. Nothing could be simpler; just run the command

wp user reset-password admin@gmail.com

This way the user receives the appropriate email. WP-CLI gives us full control over the users in the system. We can create new accounts, delete them, modify permissions, end sessions and manage roles. Importing from a CSV file is also an interesting option.

From my point of view, the most interesting option WP-CLI provides is extending the tool with your own commands.

Creating your own commands

The task manager built into WordPress has its advantages and disadvantages. It certainly works for undemanding procedures when you do not have access to the server’s cron table. In its default configuration it does not give a clear picture of when and how a given task is to be executed. When a process needs a lot of resources, relying on the built-in system is not sensible. WP-CLI with your own tasks works much better here.

It all comes down to a few lines in the application code. We need to make sure the code is included in functions.php. The most sensible approach is to create a separate file that will hold the logic of our task.

if ( class_exists( 'WP_CLI' ) ) {
    WP_CLI::add_command('my-custom-command', 'my_custom_command_function_name');
}

First, it is necessary to check whether the WP_CLI class exists. This ensures that the code will only run in the context of the command line and the WP-CLI interface. If we did not do this, it would lead to errors when trying to open any page of the website.
The add_command function takes two arguments. The first is the name of the task we will run from WP-CLI, and the second is the name of the function to be executed. You can also use the construct familiar from WordPress, passing an anonymous function as the second argument.

To run the command we have just defined, simply run this from the CLI:

wp my-custom-command

This opens up completely new possibilities for extending our application. You can imagine that with this approach we can efficiently build data import/export mechanisms, queues and many other constructs.

Summary

WP-CLI is an extremely useful tool in a developer’s hands. With it we can streamline our work with WordPress and build more advanced constructs. You will also very often see CI/CD task automation implemented with WP-CLI. To learn more about what this library can do, I encourage you to visit the project’s website https://wp-cli.org/.