The unsung awesomeness of WP-CLI shell

4-minute read
development
wordpress • wpcli • cli

I do not see nearly enough mention, or use, of the wp shell command.

By now, anyone working on WordPress projects for a living should, at the very least, know what WP-CLI is. If you do not, then take a read here.

The short version is that WP-CLI is a tool that allows skipping the WordPress UI to perform mundane tasks or script complex ones. WP-CLI is, as the name suggests, a Command Line Interface that will not run outside of WordPress but in WordPress.

That means that when you type the wp command that, in most situations, is the aliased name of the tool binary, WP-CLI will load WordPress, and with it, its current theme, must-use, and other plugins. While this is not the case for some lower-level commands, it’s accurate for most.

WordPress is a CMS (Content Management System); as such, its primary and intended use is the one to take an HTTP request as an input, say a GET request to the /2020-10-15/my-great-posts URI and go, roughly, through the following steps: load the WordPress core components like user management, session management, load the must-use plugins and active plugins load the theme, and plugins, identify the request as one for the site front-end (as is the case for this request example) identify the target area of the request (front-end as is the case for this example request, REST API, Admin UI et cetera) finally, route the request to the components that should handle it Produce output in response, the format depending on the nature of the request (e.g., HTML for a front-end request, JSON for a REST API request, and so on).

If only one could stop the loading process at step 4 from the list above, it would allow someone to tap into a fully up and running WordPress session, with all the core components, plugins, and theme loaded to “do things in the WordPress” installation.

That is precisely what the WP-CLI shell command allows. From my terminal application, I can type wp shell and be greeted by a modest, although powerful, prompt:

Sites/wp-site » wp shell
wp>

That prompt is a PHP interactive shell prompt; you could get something similar by typing php -a and being greeted by the PHP interactive shell prompt. Since this is a PHP interactive shell and not your terminal application, only PHP code and functions will make sense.

The difference, though, is that the PHP interactive shell will not load WordPress for you as the wp shell command does:

Sites/wp-site » php -a
Interactive shell

php > get_option('siteurl');

Warning: Uncaught Error: Call to undefined function get_option() in php shell code:1
Stack trace:
#0 {main}
  thrown in php shell code on line 1
php > exit
Sites/wp-site » wp shell
wp> get_option('siteurl');
=> string(19) "http://wordpress.test"
wp> exit
Sites/wp-site »

As is the case for PHP interactive shell, you can exit the WP-CLI interactive shell by issuing the exit command.

I use the wp shell command daily to debug the output of some functions deeply nested into the code and know their output or effects. Each PHP or WordPress function invoked will affect the underlying WordPress installation, requiring some care. Still, I prefer this method to test out ideas quickly or to avoid filling my code with echo, var_dump, print_r, die, and other debug methods that would entail long browser refresh trial and error approaches.

If you’ve never tried out WP-CLI, you definitely should, and if you’ve never used the wp shell command, I invite you to try it out now and get addicted.

Taking inspiration from this blog, I encourage you to make this reading worth it:

If you answer the questions below, you will create new neurons in your head through neurogenesis. But if you don’t, you will forget about 80% of what you just read tomorrow.

  1. At which step of the WordPress loading process does wp shell put you?
  2. What is the difference between wp shell and your terminal emulator?
  3. Why should you use care to use the wp shell?

Edit: some Twitter responses later, WP-CLI maintainer Alain Schlesser provided a further tip to make the WP-CLI shell even better with integration of the schlessera/wp-cli-psysh package. Just run wp package install schlessera/wp-cli-psysh and marvel at the much better output you get out of the wp shell command.