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.
wp tool is a Phar file, a PHP archive that combines a set of PHP files into a single file.
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
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
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.
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.
wp is a command-line tool and includes inline help, use
--help with any command to get additional parameters and details.
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.
wp core download
wp core download --version=5.7.3
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
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
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
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.
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.
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.
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.