The command line interface for WordPress

Just in time for your crazy load of summer projects, we have a new version of WP-CLI for you. Here’s what’s new.

Manage WP-Cron

Confused by how WP-Cron is acting? Wonder no more!

See all scheduled cron events:

$ wp cron event list
+-----------------------------+---------------------+-----------------------+------------+
| hook                        | next_run_gmt        | next_run_relative     | recurrence |
+-----------------------------+---------------------+-----------------------+------------+
| wp_version_check            | 2014-07-01 04:05:59 | 3 hours 50 minutes    | 12 hours   |
| wp_update_plugins           | 2014-07-01 04:05:59 | 3 hours 50 minutes    | 12 hours   |
| wp_update_themes            | 2014-07-01 04:05:59 | 3 hours 50 minutes    | 12 hours   |
| update_network_counts       | 2014-07-01 04:06:05 | 3 hours 50 minutes    | 12 hours   |
| wp_maybe_auto_update        | 2014-07-01 07:51:00 | 7 hours 35 minutes    | 12 hours   |
| wp_scheduled_delete         | 2014-07-01 16:06:05 | 15 hours 50 minutes   | 1 day      |
+-----------------------------+---------------------+-----------------------+------------+

Run a specific cron event:

$ wp cron event run wp_scheduled_delete
Success: Successfully executed the cron event 'wp_scheduled_delete'

Inspect registered cron schedules:

$ wp cron schedule list
+------------+-------------+----------+
| name       | display     | interval |
+------------+-------------+----------+
| hourly     | Once Hourly | 3600     |
| twicedaily | Twice Daily | 43200    |
| daily      | Once Daily  | 86400    |
+------------+-------------+----------+

Take a look at wp help cron for the full details.

Verify core checksums

To help you confirm the sanctity of your WordPress install, wp core verify-checksums fetches checksums from WordPress.org and compares them to that of your local files.

For the layperson, a checksum is a calculation of a file’s contents using the MD5 algorithm. To generate a checksum is to produce a 32 digit hexadecimal number that represents the file’s state. WP-CLI’s wp core verify-checksums command downloads WordPress.org’s reported checksums for each core file, and then compares those values to the checksum it calculates for each local file. If the values differ, then it’s an indication the file’s contents differ from what they should be.

A successful check will look like this:

$ wp core verify-checksums
Success: WordPress install verifies against checksums.

If any core files have been modified, you’ll see something like this:

$ wp core verify-checksums
Warning: File doesn't verify against checksum: readme.html
Error: WordPress install doesn't verify against checksums.

A new look

WP-CLI.org received a much-appreciated fresh coat of paint. Share the love on Twitter (or report any bugs in the issue tracker).

Other changes

Additions:

• wp * meta list: list meta values for a given post, comment, or user
• wp * meta delete: supports passing a value to match against, mimicking core behavior
• wp post generate: the --post_author=<post-author> argument supports user ID, login, or email address
• wp scaffold plugin: includes a sample readme.txt
• wp (theme|plugin) install: creates parent directories if they don’t yet exist
• wp user create: added --first_name=<first-name> and --last_name=<last-name> parameters
• wp user import-csv: a --skip-update flag will prevent updating existing users
• Clearer, more helpful messages and warnings across the board

Fixes:

• Plugins with Network: True header activate without throwing a warning on non-multisite installs
• Disabled commands no longer appear in usage docs
• Autocompletion file works properly for both bash and ZSH
• wp core update: can update directly from a ZIP file

You can browse the full list of resolved issues on GitHub.

Contributors to this release: boonebgorges, danielbachhuber, jmslbam, johnbillion, joshlevinson, mboynes, rodrigoprimo, ryanduff, scribu, szepeviktor, westonruter

The longer 0.15 soaked, the more bug fixes it saw. It’s finally time to get them into a stable release as 0.15.1:

• persist menu item data when updating a menu item; permit multiple menu items to be deleted at once
• allow widgets to be added to empty sidebars; make sure widget at index=0 is removed from sidebar when deactivated
• ignore --user when installing WordPress
• support empty DB_CHARSET value when running database commands
• throw a warning when using wp (theme|plugin) update without named entities or --all
• resolve PHP notices when using wp core update with a specified --version, or wp widget add
• use WordPress’ _n() instead of ngettext()
• fix segmentation fault in PHP 5.5.11/12 (and probably other 5.5.x versions)

You can browse the full list of resolved issues on GitHub.

Contributors to this release: boonebgorges, danielbachhuber, jmslbam, mboynes, szepeviktor, westonruter

Many thanks to the 56 people who took our first user survey. We appreciate your time in helping us understand how WP-CLI is being adopted by the community.

By the numbers

Almost 3/4 of respondents use WP-CLI actively

53% use WP-CLI multiple times per day, 20% use it a couple or few times per week, and 26% use it infrequently or rarely. 46% of respondents use WP-CLI interactively at the command line, 34% have incorporated it into bash scripts, and 18% are using WP-CLI with Puppet, Chef, or another provisioning system.

WP-CLI is largely used to install and update

Even with its variety of commands, WP-CLI is largely used to install and update. 37.5% of respondents reported using WP-CLI to install WordPress (with 30.36% using it to update WordPress), and 32.14% reported using it to update plugins and themes.

After code management, WP-CLI is popularly used (23.21%) to perform migrations. Respondents reported using wp db export and wp db import in conjunction with wp search-replace, or wp export and wp import.

A subset of respondents reported using WP-CLI to perform specialized tasks, including:

• Creating users with wp user create and wp user import-csv.
• Deleting options.
• Resizing images.
• Creating posts / pages.
• Quick code execution via wp eval, wp eval-file, and wp shell.
• Writing custom commands.

Only 38% have used community packages

WP-CLI now has 24 community packages listed in its Package Index. A good 62% percent of respondents will have the good fortune in the future to discover a helpful community package.

Feature requests

Remotely manage WordPress instances

The most common thread amongst respondents is the desire to run WP-CLI commands in one place across multiple machines. Depending on what you have access to, there are a couple of current ways to do this:

1. If you have SSH access, X-Team’s WP-CLI SSH uses your SSH connection to run WP-CLI commands on a remote machine.
2. The WP Remote CLI project proxies a subset of WP-CLI commands through WP Remote.

Better documentation

A substantial number of users requested better examples for the website. Let this be a call for contributions! Because all of the command docs are generated from the source code, adding examples or clarifying usage notes is just a pull request away.

Alternatively, you can share your shell tips, or contribute a blog post on how you’ve integrated WP-CLI into your workflow.

Grab bag of enhancements

If you have time to put together a pull request or community package, here’s a short list of requested enhancements:

• Git awareness: have plugin/core updates result in git commits (with automatically-generated messages).
• Yum integration for yum install wp-cli, yum check-update and yum update wp-cli.
• Faster algorithm for the search-replace command when dealing with large databases.
• Manage file and folder permissions for WordPress installs.
• Reset all users passwords.
• “Break in Windows less.”

WP-CLI commands to prepare meals

A good 7% of you think WP-CLI is capable of making your meals, asking for it to “make breakfast”, “make coffee ;-)”, or “dishes?”. While we can’t make any promises, we’ll continue to think about WP-CLI over breakfast and see if we get inspired.

Good news everyone! Daniel Bachhuber is the new maintainer of the WP-CLI project, which means he will be in charge of merging pull requests, releasing new versions and generally making things better.

When I started contributing to WP-CLI three years ago, it was because I had an itch to scratch. That’s no longer the case, since I’ve stopped using WordPress altogether.

Unlike me, Daniel is using WordPress and WP-CLI professionally every day, so he has a much better sense of what the pain points are. Besides that, he’s a long time contributor and has been leading many other open-source projects in the WordPress ecosystem. Therefore, I’m confident that WP-CLI is in good hands.

Please join me in welcoming him to this new role :)

A new version of WP-CLI is here. The highlights:

Manage more things

There are brand new top-level commands for dealing with more types of objects in a WordPress install:

• wp super-admin for managing caped admins on multisite
• wp menu for managing navigation menus
• wp widget and wp sidebar for managing widgets and sidebars
• wp theme mod for managing theme mods

Exporting only particular database tables

With the new wp db tables subcommand, you can generate a list of database tables, which you can pass to the wp db export command, like so:

wp db export --tables=$(wp db tables --url=sub.example.com | tr '\n' ',')

Composability is beautiful.

Arbitrary command nesting

Up until now, you could only have top-level commands, like wp search-replace and second-level subcommands, like wp core install. Now, you can have commands at any depth, such as wp post meta update.

This capability is especially useful to third-party commands, such as wp-cli-buddypress.

Revamped bash completions

Bash completions are now a bit smarter: besides auto-completing positional parameters like --dbname=, it will also suggest file names, if the subcommand you’re writing out expects a file name.

Note that after updating wp-cli.phar, you will also have to update the wp-completion.bash file.

Other changes

• added support for WordPress 3.9 and bumped minimum required version to 3.5
• disable KSES filtering when a user is not explicitly set
• allow defining skip-plugins and wp core config --extra-php in the wp-cli.yml file
• added wp role reset subcommand
• added wp transient delete-all and wp transient delete-expired subcommands
• wp core config: added --skip-check flag
• wp core is-installed: added --network flag
• wp user create: added --send-email flag
• wp user delete: added --network flag
• wp option add: added --autoload= parameter
• wp search-replace: now works with tables that have a composite primary key
• wp post create: fixed handling of --post_category= parameter
• wp eval-file: allow passing arbitrary arguments to the file

You can browse the full list of resolved issues on GitHub.

Contributors to this release: clemens-tolboom, danielbachhuber, francescolaffi, itsananderson, johnpbloch, mattheu, nyordanov, Rarst, robertboloc, rodrigoprimo, sboisvert, scribu, szepeviktor, trepmal.

Survey

We’d like to know how people are using WP-CLI so we set up a quick survey (just 5 questions). We’d appreciate it if you would fill it out. The results will be posted here, in a separate blog post.

I’m pleased to present the first release of WP-CLI in 2014, coincidentally called 0.14.0. Let’s get right into it.

Automatically detect WordPress in a subdirectory

Having WordPress in a subdirectory is a great way keep your code repository clean.

Until now, you had to explicitly tell WP-CLI how to find it, either by using the --path= parameter, or by creating a wp-cli.yml file in the root directory. With version 0.14, it will find it automatically.

To make this not-common-enough scenario work, we had to once again call upon the dark powers of eval().

Protection against running as root

If you try to run a WP-CLI command as the superuser, WP-CLI will refuse to run. In production environments, most of the commands should actually be run under the same user as the web server. But, in general, running commands as root is a bad idea.

For example, if you run wp media regenerate as root, then the newly created thumbnail files will naturally be owned by root. If the web server is running under the www-data user, it won’t be able to change these files (unless they’re globally writable, which is less secure). So, the correct command would be sudo -u www-data wp media regenerate.

If you trigger this protection, you will also receive instructions about how to disable it.

--skip-plugins global flag

Ever used WP-CLI to install a plugin that broke WP-CLI? Well, now there’s a 100% sure way to deactivate it: wp --skip-plugins plugin deactivate naughty-plugin.

You can also skip only particular plugins: wp --skip-plugins=admin-blocker,complex-beast.

Contributors to this release: bartaakos, boonebgorges, danielbachhuber, eliorivero, francescolaffi, itsananderson, Japh, jmslbam, johnbillion, mboynes, mgburns, nb, rodrigoprimo, scribu, sibprogrammer, simonwheatley, SpikesDivZero, westonruter, ziz

It’s been less than two months since the last major release of WP-CLI, and already we have a lot of goodies to show you.

Global config files

If you create a ~/.wp-cli/config.yml file, WP-CLI will read config values from that file, regardless of where you’re running it from.

You can change the path to the global config file by setting the WP_CLI_CONFIG_PATH environment variable. That means that you can also disable the global config, like so:

WP_CLI_CONFIG_PATH=/dev/null wp core install ...

The old --config global parameter is now deprecated.

Setting command parameter values in config files

What’s more, you can now define per-command config values. For example, if my config file looks like this:

core install:
	admin_user: billy
	admin_email: billy@example.com

… when I run wp core install, I don’t have to pass the --admin_user and --admin_email parameters again; they are read from the config file.

Improved plugin test templates

We have simplified the process of setting up and running plugin tests locally.

It fetches the test library from the new develop.svn.wordpress.org repository.

Also, the Travis build no longer depends on the GitHub mirror of WordPress.

Improved downloads

Firstly, all HTTPS requests now use the more up-to-date SSL CA bundle from the Requests library, which should fix most certificate warnings.

Secondly, the timeout for wp core download has been increased to 10 minutes.

Thirdly, to extract the tarball, wp core download now uses the PharData class, instead of the tar binary. This should make it work in more environments, such as MinGW.

Finally, plugin and theme downloads are now cached. So, the first time you run wp plugin install bbpress, it will save the zip locally. The second time you run it, it won’t download the zip again.

Other improvements

Additions:

• added --all flag to wp plugin deactivate
• added wp comment-meta command
• added filtering to wp plugin list and wp theme list
• added --match and --source parameters to wp rewrite list
• added --post_content flag to wp post generate
• added --skip-tests flag to wp scaffold plugin
• added --skip=image_resize to wp import

Bug fixes:

• wp core config no longer escapes HTML characters in passwords
• wp user create no longer ignores the --role parameter
• wp rewrite structure correctly flushes rewrite rules
• wp theme delete now refuses to delete the active theme
• wp scaffold post-type now generates correct capitalization
• wp plugin activate now works correctly for network-only plugins
• wp shell now works correctly even if a plugin starts output buffering
• wp core install --prompt now correctly handles the --url parameter

Misc:

• removed wp core init-tests command (context)
• renamed WP_CLI::add_action() to WP_CLI::add_hook() (context)

You can browse the full list of resolved issues on GitHub.

Contributors to this release: BoiteAWeb, ctayloroomphinc, danielbachhuber, dd32, francescolaffi, jonathanbardo, Kevinlearynet, leewillis77, nickdaugherty, QWp6t, rodrigoprimo, ryanduff, scribu, simonwheatley, tiagohillebrandt, tlovett1, wojsmol.

Shelly Bashful loves the command line. Since she’s been using it daily at work, she knows all the little tricks that make typing at the console a breeze.

She’d been put in charge of a WordPress site a few weeks ago and was sorely missing a CLI management tool. All modern web frameworks have one and Drupal has Drush. For cron jobs, she could trigger HTTP requests, but that seemed like a really roundabout way of doing things.

She figures that if she manages to load the WP environment from a CLI script, the rest would be easy. After a bit of trial-and-error, she comes up with a few lines of code:

$_SERVER['HTTP_HOST'] = 'example.com';
define('WP_ADMIN', true);
require('wordpress/wp-load.php');

Shelly is pleased; her script even works on multisite installs. Both the host name and the path to the WordPress install are hardcoded, but she can figure ways around that later.

With her geeky curiosity satisfied, she lazily types in a Google search, to check if anyone else has solved this problem. The first result is a project called WP-CLI. She installs it and tries out a few commands - it seems to work pretty well.

She then goes to the WP-CLI source and searches for ‘wp-load.php’, to see how it handles the WordPress bootstrapping - 0 results. Puzzled, she starts going through the first file that gets executed and eventually reaches one called wp-setting-cli.php. This strikes Shelly as peculiar, since she encountered a similar file in WordPress Core. She signs into the project’s IRC channel.

shelly: “Why does WP-CLI use a modified copy of the wp-settings.php file?”

After a while, someone responds:

scribu: “Because WordPress does several things that don’t make sense in a CLI context. For example, if the database tables are not installed, it prints out an HTML page with a link to the setup screen.”

shelly: “Ok, but won’t that break when WordPress adds or removes files?”

scribu: “Yes, it would, but keeping our copy up-to-date hasn’t been too difficult so far and the control it gives us is worth it. In particular, it would be tricky to avoid loading the advanced-cache.php drop-in otherwise.”

shelly: “Wouldn’t the caching problem be solved by setting WP_ADMIN to true?”

scribu: “We tried that, but it turns out there are a lot of plugins that attempt to block wp-admin access, by calling wp_redirect() and then exit(). So now we load the admin-specific code explicitly.”

shelly: “Fair enough.”

Hot on the heels of the 0.12 release comes a minor release with a few fixes:

• fixed wp plugin delete when plugin is not in its own directory
• show warning when an HTTPS request fails
• added --field= parameter to wp plugin search and wp theme search
• made the --post__in= parameter in wp post list work
• added --match= argument for wp rewrite list + other improvements

You can browse the full list of resolved issues on GitHub.

Contributors to this release: danielbachhuber, mattes, scribu

It’s been almost two months since the last major release. We have a few neat features to show you:

wp site list command

I predict that this will turn out to be the most useful command for managing multisite installs, because you can use it to loop through all of them, directly from bash even:

for url in $(wp site list --field=url)
do
	echo "$url:"
	wp --url=$url post list
done

New --field= parameter

Notice the --field=url parameter I used above? It’s available for all commands that display some information. A few examples:

wp post get 123 --field=content

wp user list --field=username

This will retrieve only the content of the post with ID 123 and nothing else.

Experimental --prompt global parameter

This nifty little parameter changes the behaviour of commands when required arguments are not passed to a command. Instead of showing an error and exiting, it prompts you for the value of each argument. Try it out:

wp theme scaffold --prompt

Phar archives are back

They were originally introduced in version 0.9 and… ahem, naively abandoned in the next release with the introduction of the installer script.

The installer uses Composer, which has its own environmental requirements, but, more importantly, it has to fetch all of the packages WP-CLI depends on, which is both less reliable and slower than downloading a single file that contains everything.

This is particularly important in a continuous integration environment, like Travis CI, where you want to have your builds run as fast as possible and fail only due to failing tests, not due to a faulty internet connection.

So, phar archives can be downloaded from the wp-cli/builds repository.

Breaking changes

• wp post get --format=content was replaced with wp post get --field=content
• the wp rewrite dump command was replaced with wp rewrite list
• the wp comment last command was removed (use wp comment list instead)

Other non-obvious changes

• wp search-replace no longer touches serialized objects (#792)
• WP-CLI will display PHP errors on STDERR, even if XDebug is not installed (#786)

New commands

• wp comment get, wp comment update and wp comment exists
• wp plugin get and wp theme get
• wp plugin search and wp theme search
• wp plugin is-installed and wp theme is-installed
• wp user add-cap, wp user remove-cap and wp user list-caps

You can browse the full list of resolved issues on GitHub.

Contributors to this release: c10b10, danielbachhuber, getsource, goldenapples, jmslbam, johnbillion, joshbetz, jtsternberg, mattes, MattiaG, mpeshev, nikolay, nullvariable, oknoway, Rarst, scribu, smhmic, stianlik, thisislawatts, trepmal, westonruter.