Version 0.24.0 released

As I mentioned in my WordCamp Europe talk:

Just like WordPress has plugins, the future of WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is 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 coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., 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 SSHSSH Secure SHell - a protocol for securely connecting to a remote system in addition to or in place of a password.’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 taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. terms assigned to posts [#2625, #2628].
  • Normalizes pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the Plugin Directory or can be cost-based plugin from a third-party / theme version numbers and headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. 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 PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. 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 sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. 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 SSLSSL Secure Socket Layer - Encryption from the server to the browser and back. Prevents prying eyes from seeing what you are sending between your browser and the server. [#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 multisiteMultisite Multisite is a WordPress feature which allows users to create a network of sites on a single WordPress installation. Available since WordPress version 3.0, Multisite is a continuation of WPMU or WordPress Multiuser project. WordPress MultiUser project was discontinued and its features were included into WordPress core. when importing users from CSV [#2690].
  • Fixes listing user metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. associated with a given username [#2700].
  • Differentiates output when moving comments to trashTrash Trash in WordPress is like the Recycle Bin on your PC or Trash in your Macintosh computer. Users with the proper permission level (administrators and editors) have the ability to delete a post, page, and/or comments. When you delete the item, it is moved to the trash folder where it will remain for 30 days. 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 themeChild theme A Child Theme is a customized theme based upon a Parent Theme. It’s considered best practice to create a child theme if you want to modify the CSS of your 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 GithubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner.

Back to work!