Our Guide to WP-CLI Command Structure

Read Time:8 Minute, 47 Second

The WordPress command line interface (WP-CLI) is an incredible tool for improving your development workflow. Understanding how commands are structured is key to using WP-CLI to its full potential. In this article, you’ll learn how to structure WP-CLI commands, including how to use parent and subcommands, as well as parameters and switches.

Before you dive into creating commands, you’ll need to install WP-CLI. The exact method differs by OS, but our guide to installing and configuring WP-CLI has everything you need.

Parent Commands and Subcommands

Almost all WP-CLI commands are structured the same way. There is a parent command for each larger area of functionality, such as wp core for working with the core WordPress installation. Each of these parent commands can be used with a number of different subcommands, and must be used with at least one.

Parent Commands Lay the Foundation

No parent command will do anything useful on its own. For example, if you try to use wp config by itself, you’ll see something like this:

That alone gives you some pretty good clues for how you would use the wp config command. You can get an even better understanding by following its advice and entering wp help config.

There are over 40 parent commands in total in the core WP-CLI installation. Some popular plugins, like WooCommerce and BuddyPress, add their own parent commands, so your WordPress installation may have even more. In most cases, you can find out how to use the command by entering wp help followed by the name of the parent command.

Understanding a bit about how they are grouped helps when learning to use WP-CLI. It’s worth noting that WP-CLI commands almost always use singular nouns in commands. For example, the parent command for user management is named wp user rather than “wp users.” As long as you remember that, you’ll find that your intuition is often correct. The command for managing comments is, indeed, wp comment and wp cron is the command you’d use for managing WP-Cron schedules and events.

You can find a cheat sheet with some of the most commonly used parent commands below.

Command Description
wp core Working with WordPress installations.
wp config Generating and reading wp-config.php.
wp plugin Managing plugins.
wp theme Managing themes.
wp user Managing users.
wp media Working with images and other media files
wp help General help. Follow it up with a command for more specific information.
wp option Setting site options, including plugin and WordPress options.
wp site Managing sites on a multisite installation.

Subcommands Give Direction

As I mentioned earlier, none of those commands really work on their own. We also need to specify a subcommand if we’re going to get anywhere. I strongly recommend setting up tab completion. This will allow you to easily see subcommands. For example, using tab completion we can see the subcommands for plugin:

Hitting enter without specifying the subcommand will prompt WP-CLI to present some additional help:

Notice a difference in how the parameters are presented in the help text above? Some are encapsulated in < > marks, others are prefixed with double dashes --. That’s not a coincidence; they are different types of parameters. We’ll get back to that in a bit.

WP-CLI is nice to work with, in that it will often be able to tell you a little bit more about each subcommand and the parameters it expects. This is very consistent throughout all the built-in WP-CLI commands. Whenever you fail to type a full command with all expected parameters it will tell you more about what it was expecting.

The cheat sheet below shows some of the more common subcommands and the parent commands they go with. There are many, many more subcommands available than the ones listed here. Some parent commands, such as wp comment, have well over a dozen subcommands, while others, like wp cron, have just a few.

WP Core

wp core download Downloads WordPress core files.
wp core install Installs WordPress.
wp core update Updates WordPress to a newer version.

WP Config

wp config create Creates a new wp-config.php file.
wp config edit Launches system editor to edit config file.
wp core update Shows the variables, constants, and file includes defined in the wp-config.php file.

WP Theme

wp theme install Installs the theme.
wp theme activate Activates the theme.
wp theme auto-updates Manages automatic updates.
wp theme deactivate Deactivates the selected theme.

WP Plugin

wp plugin install Installs the theme.
wp plugin activate Activates the plugin.
wp plugin auto-updates Manages automatic updates.
wp plugin deactivate Deactivates the selected plugin.

Parameters and Switches

In addition to a parent command and a subcommand, most of the commands need at least one parameter to be able to do something useful. For example, if you want to install a plugin you need to specify which plugin to install. Naturally the same goes for activating or deleting a plugin.

There are essentially three types of parameters you’ll use with WP-CLI: ordered parameters, named parameters, and switches.

Ordered Parameters

If a command needs more than one regular parameter, they always have to be ordered correctly for the command to function. This is why they’re called ordered parameters. They are always separated by a single space. If the parameter value itself contains spaces it needs to be surrounded by quotes.

In the help text for a command, ordered parameters are surrounded by <and >. In the following example of trying to use wp post get without any parameters, we see that id is an ordered parameter because it is enclosed in <and >.

Named Parameters

WP-CLI also works a lot with named parameters. These can be given in any order. A named parameter is recognized by the double dashes before the name and the presence of an equal sign between the name and the value.

For example, looking at the help text for wp post get above, we see that the format and fields parameters are prefixed with the double dashes. That’s how we know they are named parameters for this command.

Ordering really doesn’t matter:


There are also named parameters that are only used to indicate true/false type values. These are called switches and don’t need a value specified. If you add them to the command line, they’re understood to mean “true.” If you omit them, they are “false.”

Perhaps this is best explained with a few examples:

Not so complicated, eh? This is pretty much the norm among command line tools. But let’s add one more little detail.

Global Named Arguments

Named arguments can either be global in the sense that many WP-CLI commands use them, and they always have the same behavior when used.

Other named arguments only make sense to one specific command. This type of named argument is essentially just a named parameter. In the examples above the --quiet parameter is global because it affects all commands in the same way. But the --format parameter is not considered global because it doesn’t make sense for all commands.

How to Use WP-CLI Commands

As an example, let’s look at how to use wp-plugin to install and activate a WordPress plugin. Along with managing users, this is one of the first areas new WP-CLI users want to learn about. Even if you are not terribly interested in managing plugins from the command line, it’s worth reading this section to get warmed up for working with WP-CLI.

Installing a new plugin from the WordPress repository is very straightforward. You need a parent command (wp plugin), a subcommand (install), and an ordered parameter (the plugin’s official slug) to install the plugin. Activating the plugin uses a similar command, but with a different subcommand (activate).

Put everything together and you should see something like this:

As you can see, installing and activating a plugin is two separate things in WP-CLI, just as it is when you install a plugin using the web interface. But installing and then directly activating a plugin is so common that WP-CLI has a way to do both at the same time:

One tricky part is finding the right slug for the plugin you want. All plugins are identified by their official slug, but in many cases the slug isn’t even remotely similar to the plugin’s official name. The wildly popular Yoast SEO plugin has the slug wordpress-seo. The slug for our own plugin WP Offload Media is amazon-s3-and-cloudfront.

Slugs are assigned when plugins are first accepted to the WordPress plugin repository and are the only unique identifiers. Even if the name of the plugin changes, the slug remains the same. You can always go to the plugin repo webpage, search for the plugin and look at the path in the URL:

You can see a plugin's slug by viewing it's URL in the repository, but WP-CLI offers a more elegant solution.

It works, but it lacks finesse and takes you out of your terminal. Here’s the proper way to do it using WP-CLI’s search subcommand:

If you’re keen to learn more about managing plugins, we will dive into all the nitty gritty aspects of the wp plugin command in a later post about WP-CLI. For now we’re just using it as a way to demonstrate using parameters.

Wrapping Up

The biggest benefit you’ll see from integrating WP-CLI into your development workflow is likely just how much faster it lets you work. Practically anything you can do from the WordPress admin can be accomplished in less time using the command line.

Once you know the basics, you can take WP-CLI even further with our list of WP-CLI packages we can’t live without.

Understanding how commands, subcommands, and parameters are structured is key to getting comfortable with WP-CLI. My intention is to provide you with the basic knowledge you need to start experimenting on your own. If you have any questions about how to structure your WP-CLI commands, parameters, or anything else WP-CLI related, please let me know in the comments.

Source: https://deliciousbrains.com/wpcli-command-structure-guide/