mkaz.blog

The WordPress Command Line Tool

One of my favorite WordPress tools is WP-CLI, the wp command-line tool.

The tool allows you to do numerous things from installing WordPress, to upgrading, installing, and activating plugins and themes, configuring installs, and even generating dummy content.

I'll include a few of the most common things, check out the official WP-CLI documentation for more.

Install

The wp tool is a Phar file, a PHP archive that combines a set of PHP files into a single file.

Linux Server

If you are using a Linux server, or other UNIX-like environment, the easiest way to install is to download the latest release from GitHub and set as executable.

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

You can run that as the binary, but typically everyone renames it to wp and puts it some place on your path. My typical install includes the following step:

mv wp-cli.phar ~/bin/wp

Local by Flyheel

If you are using Local, which I highly recommend as the easiest way to run WordPress development sites, it comes with wp command-line tool installed. You can access the shell by right-clicking on your server and selecting Open Site Shell

Local - Open Site Shell

After launching the shell, you will be in a terminal and can type any wp command.

wp-env

If you are using wp-env tool to create your WordPress dev environment, then WP-CLI is already installed, the wordpress:cli Docker image is included by default. To use with wp-env, send the commands with wp-env run cli

For example, to install my Code Syntax Block plugin, you could use:

wp-env run cli plugin install code-syntax-block

Docker

If you use Docker you can add the wordpress:cli image to your installation. Instead of Docker, I recommend using wp-env as an easier tool that is custom built to manage WordPress sites and underneath, it is powered by Docker.

Usage

Ok, on with the show. In the examples that follow, I'll show running WP-CLI using the wp command. If you are using wp-env, substitute with the command you use. Commands should be run from the WordPress install directory.

Remember wp is a command-line tool and includes inline help, use --help with any command to get additional parameters and details.

Download WordPress

You can use wp to download any version of WordPress. This is typically how I install a new test site. Starting from an empty directory.

Latest version: wp core download

Specific version: wp core download --version=5.7.3

Nightly Beta: wp core download --version=nightly

Configure WordPress Install

After downloading WordPress, you need to configure it. Use wp config create to setup the wp-config.php with database parameters and additional settings.

wp config create --dbname=wptest --dbuser=webuser --dbpass=password

The download and configure is how I automate setting up a local site, it still requires setting up a virtual host in your web server but takes out a few steps.

If you want to set debug variables use:

wp config set WP_DEBUG true --raw
wp config set SCRIPT_DEBUG true --raw

Setting up WordPress

A common use for WP-CLI is installing plugins or themes using wp.

Install the Code Syntax Block plugin and activate:

wp plugin install code-syntax-block --activate

Install the Tove theme and activate:

wp theme install tove --activate

Note: The plugin and themes are pulled from the WordPress.org directories.

You can also uninstall plugins and themes:

wp theme uninstall twentytwenty
wp plugin uninstall hello

Disable Widgets

A default WordPress install often includes a set of widgets that I typically do not want. You can remove them using wp. First, I list the sidebar name to illustrate where it comes from.

> wp sidebar list
+------------------+---------------------...
| name             | id                  ...
+------------------+---------------------...
| Footer           | sidebar-1           ...
| Inactive Widgets | wp_inactive_widgets ...
+------------------+---------------------...

List the widgets in a specific sidebar.

> wp widget list sidebar-1
+-------+---------+----------...
| name  | id      | position ...
+-------+---------+----------...
| block | block-2 | 1        ...
| block | block-3 | 2        ...
|       |         |          ...
|       |         |          ...
| block | block-4 | 3        ...
|       |         |          ...
|       |         |          ...
+-------+---------+----------...

Remove all the widgets.

> wp widget reset sidebar-1
Sidebar 'sidebar-1' reset.
Success: Reset 1 of 1 sidebars.

Confirm widgets are removed.

> wp widget list sidebar-1
+------+----+----------+---------+
| name | id | position | options |
+------+----+----------+---------+
+------+----+----------+---------+

Working with Posts and Pages

A default WordPress install includes a couple posts and a comment. You can delete those from the command-line. First, you may want to check that they are the ones you want to delete.

> wp comment list
​
+------------+-----------------+--------...
| comment_ID | comment_post_ID | comment...
+------------+-----------------+--------...
| 1          | 1               | 2021-10...
+------------+-----------------+--------...

You can then delete the comment using the comment id.

wp comment delete 1 --force

You can do the same for posts and pages. Here's how you would just list pages

wp post list --post_type=page

Generate Test Content

The generate command is helpful to create some test content. When developing for WordPress it is helpful to test the limits, a menu might look great when there are two pages but what happens for a site with a thousand pages.

wp post generate --count=1000 --post_type=page --max_depth=3

You can also generate posts and prefill it with some content. Here's an example from the --help that creates 10 posts and fetches filler text and sets as the post content. The 5 used in the API is how many paragraphs to generate. Each post will contain the same post content.

curl -N http://loripsum.net/api/5 | wp post generate --post_content --count=10

Upload Media

You can use wp to import media, this can be from local files or from external URLs.

wp media import https://mkaz.com/wp-content/uploads/2017/03/XP202095.jpg
wp media import https://mkaz.com/wp-content/uploads/2017/03/XP202096.jpg
wp media import https://mkaz.com/wp-content/uploads/2017/03/XP202107.jpg

You can do multiple imports on the same line, but I separated here for better readability.

Import/Export Sites

Many of the functions that you can do within /wp-admin/ have a CLI counterpart. For example, importing and exporting an entire site to a WXR file.

> wp export
public>wp export
Starting export process...
Writing to file wpbeta.wordpress.2021-10-23.000.xml
Success: All done with export.

Then on your new site, you can import using

wp import wpbeta.wordpress.2021-10-23.000.xml

See the command-line help or documentation for additional settings that can limit exports by date, author, post id, and so on.

Stay Current

The WP-CLI can keep itself up to date. Use wp cli check-update to see if an updated version exists and use wp cli update to self-update the command.

Summary

Hope this was useful, and you picked up a few tips. Create a test site and try playing with the wp tool. Browse through the --help to see list of commands and additional information on each.

If you have additional tips how you use WP-CI, please share in the comments.