WordPress

The Beginner’s Guide to WP-CLI

Lines of code on computer screen

 

Lines of code on computer screen

Imagine Peter Parker staring up at a brick wall.

Sure, he could climb that facade like your average disaffected high school student. All it would take is a harness, Mary Jane on belay, and a whole lotta of heaving.

Or . . .

He could strip down to his Spidey suit and one-shot web sling his way to the top.

The average WordPress user is a bit like Peter Parker. With some time and work, it’s possible to get your website to do exactly what you want it to just by using the platform’s simple admin dashboard.

But if you’re a power user — admit it, you’re wearing stretchy pants right now — you can sling your way past a variety of time-consuming tasks that crop up because of WordPress’s intentionally simple interface.

Your web?

WP-CLI, which turns tedious tasks into short commands that take mere seconds to execute.

WP-CLI gives you direct access to WordPress capabilities using the command line. This is helpful during regular development and also makes server automation possible. Automation is particularly helpful if you manage more than one or two WordPress installations.

In this article, I’ll first explain how a CLI works and then introduce a few ways WP-CLI can improve your own development workflow. Finally, let’s talk through some of the most fundamental tasks WP-CLI makes possible.

Remember, Peter, with great power comes a great website.

Brush up on the differences between WordPress.com and WordPress.org before you get started.

What Is a Command Line Interface (CLI)?

The WordPress administrative dashboard is an example of a Graphical User Interface (GUI). You are able to interact with visual elements to execute technical commands, which are then generated and handled behind the scenes.

Then there’s the command line.

This gives you more direct access to your files and database. However, using the command line means you’ll need to better understand what’s happening on your server behind the scenes, and how to trigger certain tasks using special commands. If you enter the wrong command, you could irreparably delete all of your files (remember, good backups are everyone’s business)!

The console is the program that gives you access to the command line. Every computer (and by extension, every server) has a console program installed. It is one of the oldest computer programs and used to be the primary way you could interact with a computer’s capabilities.

To use the command line on your local computer, you can simply open up your pre-installed console for issuing commands:

  • For Mac and Linux users, this is called the Terminal. On Windows, look for Command Prompt (and keep in mind that you’ll also need to install an SSH client).
  • If you want to access the command line for a remote environment, such as your website’s hosting server, you’ll need SSH credentials provided by the server. You can then access your local command line tool to use SSH and log in remotely.

While the command line is present on every computer, not all web hosting providers allow their users access to remotely log in. You will need to check with your own hosting provider, but these are three of the  most common scenarios:

  1. SSH and CLI access is disabled entirely. WP-CLI will not be available to you.
  2. SSH and CLI access is available but limits you to using certain commands. WP-CLI may or may not be included, and may be present but with certain limitations.
  3. SSH and CLI access is available without any restrictions. If WP-CLI isn’t pre-installed, you can easily install it yourself.

If you can’t tell what is available to you by reading the literature on your hosting company’s website, contact technical support to determine which of the three categories they fall into. If your hosting provider falls into the second category, contact them to discover whether WP-CLI is offered and what limitations are present (if any).

Our recommendation? Sign up for DreamPress, the premier WordPress hosting service.

Introducing WP-CLI

WP-CLI is an open-source project recently brought into the fold of official WordPress.org development projects. The project name is an abbreviation for ‘WordPress Command Line Interface’. The tool is a framework for working with WordPress from the command line and includes a series of commands for common tasks.

If you are more than a casual WordPress user, WP-CLI can significantly reduce the amount of time you spend managing your WordPress website(s). There are a few reasons for this. First, typing is nearly always faster than attempting to click your way through a graphical interface. Once you identify which commands you need, you can quickly copy and paste in everything at once and watch your WordPress sites practically manage themselves.

Then, once you get the hang of WP-CLI, you can enter into the wonderful world of automation. You can write short scripts that invoke WP-CLI to back up and update your sites on a regular basis. These could be run via a cron job daily, weekly, monthly, or at any other interval you choose.

Finally, there are also useful commands to help you circumvent issues that are otherwise nearly insurmountable using the regular interface. For example, what happens if an admin has lost their password, and their email is also no longer current? Normally this would be difficult to resolve, but with WP-CLI, you can easily update their email and password to restore access.

Since WP-CLI is open source, it is completely free.

And DreamHost offers SSH and the full spectrum of WP-CLI to help you manage your WordPress installation from the command line. You’ll simply need to ensure your account has SSH activated, and get it set up for use with your local computer.

WP-CLI comes with many commands that enable you to run most of your WordPress website from your command line. A few of the major options include:

  • wp core for managing WordPress core files
  • wp comment for regulating comments
  • wp db for interacting with the database
  • wp export for exporting your content
  • wp media for importing or regenerating media
  • wp option for updating options
  • wp post for managing your posts
  • wp scaffold for generating standard code registering post types, taxonomies, plugins, and more
  • wp theme for managing your themes
  • wp user to control your user list
  • wp doctor for diagnosing problems
  • wp profile for identifying performance issues

Now that you’re up to speed on WP-CLI and have gotten a glimpse of its possibilities, let’s take a look at different ways you can use it in the real world.

How much does it actually cost to run a WordPress website? You might be surprised.

Example Use Cases for WP-CLI

Aside from simply being faster to use for general site management, automation is one of the biggest advantages of using WP-CLI. For example, you can automatically push updates to all your client sites using WP-CLI. Linking multiple sites to WP-CLI this way enables you to automatically update WordPress core files, themes, and plugins. What’s more, all of this is possible with a single command (which we’ll discuss in more detail in a later section)!

At this point, you should have a feel for what WP-CLI is and how you’ll be able to use it to supercharge your WordPress development.

Now let’s get your spider-senses tingling (ew!) with some of the fundamental commands.

8 Fundamental Commands for Using WP-CLI Effectively

WP-CLI is capable of handling many tasks, and you can write your very own! However, there are a few fundamentals you can use right away that will immediately save you time when managing WordPress on your server.

We’ll show you how to complete several key tasks. While these are only the tip of the iceberg, mastering these tasks using WP-CLI will help you save many hours spent managing the basics of your WordPress website.

Plus, they will serve as an interactive way for you to get comfortable with using WP-CLI on a regular basis.

1. Ensure That WP-CLI Is Set Up On Your Server

Checking for and installing WP-CLI on your web server will require SSH. I’ll assume you are already set up to use SSH to access your server (as we discussed previously). Of course, if you’re a DreamHost customer, you can skip this step and be assured that WP-CLI is ready to go.

Before doing anything else, you should determine whether or not WP-CLI is already installed for you. Here are the steps you can take to find this out:

  1. Log in to your server with SSH.
  2. Enter the command wp –info
  3. If you see ‘Command not found’, WP-CLI is not installed.

If WP-CLI is already installed, you can skip the rest of this section and get started with your first commands. Otherwise, follow these steps to install WP-CLI on your server. We’ll show you the recommended method for installation.

First, make sure your server meets the minimum requirements for WP-CLI. This means your environment needs to match the following versions (or have a higher version) for each:

  • UNIX-like environment (OS X, Linux, FreeBSD, Cygwin); limited support in Windows environment.
  • PHP 5.3.29 or later, which can be found using the php -v command on your server over SSH.
  • WordPress 3.7 or later. This can be found in the lower right-hand corner of your WordPress admin.

If you’re not sure whether you are running on UNIX, your hosting provider’s support team should be able to help. Assuming you meet these requirements, it’s time to download the wp-cli.phar file.

Use your command line program to enter the following curl command:

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

Next, we’ll need to verify that the Phar file is working as expected, using the php command:

$ php wp-cli.phar --info

Finally, to make the WP-CLI command available as wp, you’ll need to make the file executable and move it to where your server will recognize it as a default command. This is done using chmod and mv, though the specific locations may vary depending on your server setup:

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

At this point, you should be able to use the wp command like normal. You can test it by running the official wp command:

$ wp --info

If everything is working, you’ll get a message similar to this:

$ wp --info
PHP binary:    /usr/bin/php5
PHP version:    5.5.9-1ubuntu4.14
php.ini used:   /etc/php5/cli/php.ini
WP-CLI root dir:        /home/wp-cli/.wp-cli
WP-CLI packages dir:    /home/wp-cli/.wp-cli/packages/
WP-CLI global config:   /home/wp-cli/.wp-cli/config.yml
WP-CLI project config:
WP-CLI version: 1.3.0

Now that WP-CLI is installed, you can start using it in your WordPress development process. You can also install it the same way on your computer, by logging out of SSH and repeating the process within your local development environment.

2. Start a New WordPress Site

If you develop for WordPress, you’ve likely set up many new installations of it on your local computer. With WP-CLI, you can turn WordPress’ famous 5-minute installation into practically a 5-second installation using wp core.

Normally, you would need to load up WordPress in your browser and follow a few pages of prompts. Again, for your average user this is not a problem. It’s when you need to repeat this process many times over for development purposes that it becomes tiresome. Instead, you can simply run an installation using the provided wp core command to download and set up WordPress.

First, download the WordPress files into your server folders:

$ wp core download

Next, set up WordPress’ connection to your database with wp config, modifying the parameters to match your database details:

$ wp config create --dbname=testdb --dbuser=wp --dbpass=yourpassword

Finally, modify the install command to include the proper settings for your new WordPress site:

$ wp core install --url=example.com --title=Example --admin_user=adminusername --admin_password=yourpassword --admin_email=admin@example.com

That’s it! You’ve now downloaded and installed a brand new WordPress site. It took three lines of code and zero clicking around the browser.

On the other hand, if you’re using DreamHost you can easily create a new WordPress site using your control panel. That way, we’re able to manage the installation process for you, ensuring that it goes as smoothly as possible.

3. Install Updates to WordPress Core

If you already run a WordPress website, you can still benefit from WP-CLI right away. Keeping WordPress core up to date is important for security, and for compatibility with the latest themes and plugins.

This process uses the wp core command as well, to update both the files and database of your WordPress site:

$ wp core update
$ wp core update-db

The first command updates all of your files, and the second runs any necessary updates to the database. If you’re running your site on a DreamHost plan such as DreamPress, however, you don’t need to worry about this particular command. We’ll automatically upgrade your site when a new major version of WordPress comes out, so it will stay up to date.

You can use a command to force a downgrade as well. If you upgraded and later ran into a compatibility issue with a vital plugin on your website, you could downgrade using this command:

$ wp core update --version=VERSION_NUMBER --force

This way, you can always access any version of WordPress you need to at any time. This also makes testing for version compatibility a lot quicker. Of course, it’s always best to try and fix the plugin issue before resorting to downgrading it, since an older version of a plugin can introduce potential security issues.

4. Set Up Themes

You can also install and activate themes using WP-CLI. Typically, you would need to log into your admin and visit Appearance > Themes and manage your desired themes from there. However, you can type in a few short commands to review and choose whichever theme you need.

First, you can check which themes are currently on your WordPress website with wp theme list:

$ wp theme list

Next, you can use wp theme search <term> to find your desired theme:

$ wp theme search illdy

Then, you can install and activate your desired theme based on its slug:

$ wp theme install <slug>
$ wp theme activate <slug>

With that, you’re all set! These few commands will get your site’s theme up and running.

5. Add, Delete, Activate, and Deactivate Plugins

Not only can you set up themes with WP-CLI, but you can manage your WordPress site’s plugins. This can come in handy for adding new plugins, deleting problematic plugins, or even activating and deactivating plugins. You would normally need to manage these tasks using the WordPress dashboard plugin section.

The commands for managing plugins are similar to those for themes. For a start, you can review currently installed plugins with wp plugin list:

$ wp plugin list

You can also search for new plugins using wp plugin search <term>:

$ wp plugin search <term>

Once you’ve found the plugin you’re looking for, you can install, activate, and deactivate at will:

$ wp plugin install <slug>
$ wp plugin activate <slug>
$ wp plugin deactivate <plugin-name>

Additionally, you can update all your plugins at once:

$ wp plugin update --all

With these commands, you’ll be able to fly through plugin management and not waste any time waiting for browser buffering or dealing with errors within PHP.

6. Manage Your Content With WP-CLI

If you’re in a pinch, you can even make content changes using WP-CLI. You can add, delete, and update posts, all from the command line.

Use the wp post list command to create a list of your existing posts:

$ wp post list

You can reference the relevant ID number to update a post using wp post edit <id>:

$ wp post edit 1

This will open up a text editor within your command line program that enables you to edit your content. Save and close the file to push the changes to your WordPress site.

Alternatively, you can create a new post altogether, using wp post create:

$ wp post create --post_status=publish --post_title="Second Post" --edit

The final edit flag will again open a text editor where you can easily write and save your post. The post_status flag can be any of the registered post statuses, such as publish, draft, or pending.

To delete a post, use the delete command and the post’s ID number:

$ wp post delete <id>

While the user interface may provide more control over the visual presentation of a post, this is a great approach for those who prefer the minimalist environment of a plain text editor.

7. Run Nearly Any Database Query With WP-CLI

For more advanced developers, it might be necessary to examine custom database queries or test existing queries for efficiency. Whatever the reason, if you are interested in creating or editing database queries, WP-CLI enables you to write them directly in the command line.

Typically, this is not possible with a normal WordPress installation. You would need special database plugins or additional GUI access to the database through your hosting provider.

If you want to access the regular MySQL command line interface using your WordPress credentials, use the wp db cli command:

$ wp db cli

However, you can also execute MySQL queries directly from WP-CLI. These queries can be made using the wp db query command. For example, let’s say you want to select all users so you can see their user logins and ID numbers:

$ wp db query "SELECT user_login, ID FROM wp_users;"

This will return a table with the selected information for your users. You can grab one of the author IDs, and then list all the posts that author has written:

$  wp db query "SELECT post_title FROM wp_posts WHERE post_author=<id>;"

Which MySQL commands you’ll need to run will depend on the work you’re doing, but you can clearly see how easy WP-CLI makes it to interact with your database.

8. Access the WP-CLI Help Manual for Guidance

As you may have realized by now, WP-CLI comes packed with a huge amount of power through its many commands. It can become a little difficult to keep up! Thankfully, the tool includes a robust help system.

You can use the wp help command to access support at any time:

$ wp help

Typing this in will provide you with a complete list of command options. You can add the command you need information for at the end to get help for it specifically. For example, let’s say you need to know more about the wp plugin command:

$ wp help plugin 

This will provide you an in-depth information page about using this command. You can do this for each subcommand as well. For example, the wp plugin install command has its own help manual:

$ wp help plugin install

Each built-in WP-CLI setup has this feature, so you can explore its power at your own leisure. You can also find much of the same information and support on the WordPress.org Developer Resources website.

Master and Commander

In the end, WP-CLI is a powerful tool for managing WordPress sites efficiently, simplifying many tasks that otherwise take a lot of time to execute manually using the GUI. This is particularly helpful for you power users out there working with multiple installations of WordPress at once.

What questions do you have about getting started with WP-CLI? Let us know in the comments section below!

Ready to take your website to the next level? Power up with DreamPress.

About the author

Megan Hendrickson

Megan started her career in women's magazines, but after authoring waaaay too many "Walk Off the Weight" columns, she merged into the tech lane. She writes and edits for DreamHost and shares an inordinate amount of WordPress content on Twitter.