Version 0.24.0 released

As I mentioned in my WordCamp Europe talk:

Just like WordPress has plugins, the future of WP-CLI is packages of commands. For this future, I’m trying to proactively solve the problems WordPress has with plugins:

  • Where WordPress plugins are considered second-class to what’s included in core, I’d like WP-CLI packages to be considered first-class citizens amongst the commands in WP-CLI.
  • All too often, WordPress plugins have just one author. I’d like for each WP-CLI package to have two or three active maintainers.

In this model, WP-CLI becomes the common interface, and supporting application layer, to a rich ecosystem of features. Doing so opens more frontiers for innovation, which leads to a greater selection of ideas to choose from. And because more people are involved in authoring packages, WP-CLI benefits from a larger contributor pool.

With this model, my focus shifts towards designing a world-class experience for WP-CLI package authorship. Read through the commands cookbook for a thorough introduction to creating a WP-CLI command. Check out wp scaffold package [repo] for the easiest way to generate the boilerplate for your new WP-CLI package. Weigh in with your thoughts on how we should evolve the WP-CLI package index. And follow @runcommand as I explore commercializing WP-CLI products and services — I hope that runcommand is just the first of several WP-CLI-based businesses.

One last ask: if you care about the WP-CLI release cycle, or dependencies and backwards compatibility, please let me know how often you think WP-CLI should be released.

Let’s get on with the show. Use wp cli update to install v0.24.0, representing 449 resolved issues and pull requests. Here’s what’s new.

Forked wp-settings.php no more

Every application has a bootstrap file which loads all of the requisite utilities needed to serve a request. In WordPress, this is called wp-settings.php.

Since v0.8.0 [#261], WP-CLI has used a forked version of this bootstrap file, called wp-settings-cli.php, to give it more control over the load process, providing features like --skip-plugins. But, because WordPress can require new files from wp-settings.php, maintaining a forked version has the unfortunate side effect of WP-CLI regularly breaking when a new version of WordPress is released.

Thanks to coordinated changes in the WordPress project, WP-CLI v0.24.0 returns to loading wp-settings.php for WordPress 4.6 and higher [#2278]. Doing so should make WP-CLI more future proof against new versions of WordPress.

More documentation in more languages

Thanks to tireless efforts by a solid group of contributors, WP-CLI now has more documentation in more languages.

Want to get involved with WP-CLI’s documentation? Check out the Github issues labeled “scope:documentation”.

Effortlessly use WP-CLI against any WordPress install

WP-CLI aliases are shortcuts you register in your wp-cli.yml or config.yml to effortlessly run commands against any WordPress install.

For instance, if I’m working locally on the runcommand theme, have registered a new rewrite rule, and need to flush rewrites inside my Vagrant-based virtual machine, I can run:

$ wp @dev rewrite flush
Success: Rewrite rules flushed.

Then, once the code goes to production, I can run:

$ wp @prod rewrite flush
Success: Rewrite rules flushed.

Look ma! No more SSH’ing into machines, changing directories, and generally spending a full minute to get to a given WordPress install.

Additionally, alias groups let you register groups of aliases. If I want to run a command against both runcommand WordPress instances, I can use @both:

$ wp @both core check-update
Success: WordPress is at the latest version.
Success: WordPress is at the latest version.

Aliases can be registered in your project’s wp-cli.yml file, or your user’s global ~/.wp-cli/config.yml file:

  ssh: vagrant@
  - @prod
  - @dev

But wait, what’s the ‘ssh’ in there?

WP-CLI now natively supports a --ssh=<host> global parameter for running a command against a remote WordPress install. Many thanks to XWP and their community for paving the way with WP-CLI SSH.

Under the hood, WP-CLI proxies commands to the ssh executable, which then passes them to WP-CLI installed on the remote machine. Your syntax for -ssh=<host> can be any of the following:

  • Just the host (e.g. wp, which means the user will be inferred from your current system user, and the path will be the SSH user’s home directory.
  • The user and the host (e.g. wp
  • The user, the host, and the path to the WordPress install (e.g. wp The path comes immediately after the TLD of the host.

Or, if you use a ~/.ssh/config, <host> can be any host alias stored in the SSH config (e.g. wp --ssh=rc for me).

Note you do need a copy of WP-CLI on the remote server, accessible as wp. Futhermore, --ssh=<host> won’t load your .bash_profile if you have a shell alias defined, or are extending the $PATH environment variable. If this affects you, here’s a more thorough explanation of how you can make wp accessible.

Relevant pull requests for aliases and SSH support include: #2755, #2974, #3012, #3013, #3014, #3016, #3026, #3040, #3070, #3093, #3100, #3117, #3134, #3135, #3145, #3161, #3180.

Everything else in 0.24.0

Command improvements:

  • Adds a newline when using the wp shell interactive prompt [#2601, #2659].
  • Improves formatting of scaffolded plugins [#2588, #2598].
  • Introduces --format=ids to wp (*) generate commands for easier chaining [2622].
  • Adds term recount command for trigger a recount of taxonomy terms assigned to posts [#2625, #2628].
  • Normalizes plugin / theme version numbers and header formatting when scaffolding [#2644].
  • Introduces --due-now to run all cron events due or overdue [#2658].
  • Permits wp cron (event|schedule) list and wp option list to output a single field [#2657, #3033].
  • Adds field filtering in cron event list command [#2674].
  • Includes a .distignore file when scaffolding a new plugin, to define files and folders excluded from distributions [#2697, #2756, #3042, #3088].
  • Displays a summary success message when using --dry-run with wp search-replace [#2740].
  • Scaffolds plugin based on supported WordPress version [#2751].
  • Applies extended insert format to search-replace SQL export, for a substantial performance boost [#2745].
  • Warns with wp core verify-checksums when extra files exist in wp-admin or wp-includes [#2638].
  • Supports --format=<format> argument for wp cap list, wp user list-caps, and wp super-admin list [#2851, #2961, and #2949].
  • Accepts multiple term IDs with wp term url [#2865].
  • Supports PHP 5.5 Memcache extension when checking cache type [#2945].
  • Uses WP_CLI::warning() when a theme is already active, to make behavior more consistent with plugin activation [#3015].
  • Adds --porcelain flag to wp db export [#3032].
  • Allow the author field to be selected in wp theme list --fields=<field> [#3043].
  • Introduces wp widget reset <sidebar>, for removing all widgets from a sidebar and placing them in the inactive sidebar [#3077].
  • Supports ‘trunk’ and ‘nightly’ version arguments for wp core download [#3127].
  • Adds verbosity to wp role reset [#3132, #3141].
  • Adds --include-columns=<columns> argument to wp search-replace [#3142].
  • Adds --ci=<provider> argument for wp plugin test scaffold, which supports ‘travis’, ‘circle’, or ‘gitlab’ [#3144, #3163].

Framework enhancements:

  • Uses is_callable() in WP_CLI::add_command(), instead of custom logic [#2595].
  • Introduces CompositeCommand->remove_subcommand(), and modifies the bootstrap process to always register core commands [#2629].
  • Runs before_invoke and after_invoke callbacks on subcommands, such that you can hook into immediately before and after subcommand execution [#2647, #2686].
  • Introduces --debug=<group> to limit debug output to a particular group of debug calls [#2648].
  • Interacts with the Package Index over SSL [#2720].
  • Supports CSV with spaces when using --fields=<fields> [#2750].
  • Disables WP cron when ALTERNATE_WP_CRON is defined [#3118].
  • Supports positional arguments defined in wp-cli.yml [#3120].
  • Introduces WP_CLI_STRICT_ARGS_MODE for dealing with arg ambiguity [#3128].
  • Registers --http=<url> global parameter for use with RESTful WP-CLI [#3130].
  • Introduces WP_CLI::add_wp_hook(), for adding actions and filters when you don’t yet have access to actions and filters [#3195].
  • Increases minimum supported PHP version to 5.3.29 [#2672].

Bug fixes across the board:

  • Mitigates a DateTime fatal when instantiating the Composer object [#2607].
  • Squashes wp export notice about skip_comments [#2620].
  • Avoids regex to fix greedy parsing of parameter arguments [#2587, #2717].
  • Ensures default and options are used when supplied as arg args [#2741].
  • Considers image sizes missing when using wp media regenerate and sizes doesn’t have registered sizes [#2645].
  • Catches WP_Error from translations_api() [#2671, #3179].
  • Doesn’t erroneously try to (de)activate plugins with --all flag [#2692].
  • Defines DOING_CRON before WordPress is loaded when running wp cron event run [#2691].
  • Only attempts to use add_user_to_blog() on multisite when importing users from CSV [#2690].
  • Fixes listing user meta associated with a given username [#2700].
  • Differentiates output when moving comments to trash from output when deleting comments [#2701].
  • Prevents runaway memory usage from wp export by clearing object cache after each file [#2716].
  • Ignores ambigious empty plugin and theme slugs when installing [#2715].
  • Takes all digits when running commands that use the comment id [#2714, #2901].
  • Only displays packages directory path when it exists [#2773].
  • Bails early in theme commands if theme is broken or has error [#2798].
  • Displays error if theme directory exists but is erred; permits force install [#2821].
  • Fixes PHP notice when installing a child theme, and running wp theme status [#2976, #3047].
  • Ensures YAML formatter handles objects and --fields=<fields> arg [#3060].
  • Fixes exception in wp menu list if --format=ids [#3075].
  • Populates recently active plugins list when deactivating a plugin [#3068].
  • Respects wp-cli.yml default values when applying argument defaults [#3111].
  • Calls wp_slash() on data passed to post, comment, term, and user commands [#3156, #3157, #3158, #3159, #3167, #3173].
  • Appropriately lists duplicated cron events [#3175].

Contributors to this release: andyexeter, bordoni, danielbachhuber, diggy, enrico-sorcinelli, ernilambar, geo4orce, gedex, gilbitron, hideokamoto, apertureless, JRGould, johnbillion, kkoppenhaver, kouratoras, markjaquith, miya0001, mustafauysal, NateWr, Nikschavan, ocean90, petenelson, phh, rachelbaker, PatelUtkarsh, PeterDaveHello, robhenley rodrigoprimo, roelveldhuizen, ShinichiNishikawa, shulard, stephenharris, stevenkword, swissspidy, taianunes, villevuor, voldemortensen, wesm87, 8bitodyssey

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

Back to work!