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.
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
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
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
$ 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
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 --ssh=runcommand.io), 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.
- The user, the host, and the path to the WordPress install (e.g.
wp --firstname.lastname@example.org~/webapps/production). The path comes immediately after the TLD of the host.
Or, if you use a
<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
--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
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
- Adds a newline when using the
wp shell interactive prompt [#2601, #2659].
- Improves formatting of scaffolded plugins [#2588, #2598].
wp (*) generate commands for easier chaining .
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].
--due-now to run all cron events due or overdue [#2658].
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
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].
--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].
WP_CLI::warning() when a theme is already active, to make behavior more consistent with plugin activation [#3015].
--porcelain flag to
wp db export [#3032].
- Allow the author field to be selected in
wp theme list --fields=<field> [#3043].
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].
--include-columns=<columns> argument to
wp search-replace [#3142].
--ci=<provider> argument for
wp plugin test scaffold, which supports ‘travis’, ‘circle’, or ‘gitlab’ [#3144, #3163].
WP_CLI::add_command(), instead of custom logic [#2595].
CompositeCommand->remove_subcommand(), and modifies the bootstrap process to always register core commands [#2629].
after_invoke callbacks on subcommands, such that you can hook into immediately before and after subcommand execution [#2647, #2686].
--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
- Disables WP cron when
ALTERNATE_WP_CRON is defined [#3118].
- Supports positional arguments defined in
WP_CLI_STRICT_ARGS_MODE for dealing with arg ambiguity [#3128].
--http=<url> global parameter for use with RESTful WP-CLI [#3130].
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].
wp export notice about
- Avoids regex to fix greedy parsing of parameter arguments [#2587, #2717].
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].
translations_api() [#2671, #3179].
- Doesn’t erroneously try to (de)activate plugins with
--all flag [#2692].
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 ambiguous 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
- Populates recently active plugins list when deactivating a plugin [#3068].
wp-cli.yml default values when applying argument defaults [#3111].
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!