Meet wpshell – the power of WordPress at your prompt

Developing in WordPress is a lot of fun for me and there are great plugins that make developing and debugging WordPress code really simple. Debug-Bar, Debug-Bar-Extender and Debug-Console are my favorite WordPress plugins to do this.

But if you really live in WordPress code all day long you might sometimes wish that you can just log into it and do your thing without the need of leaving test scripts all over the place.

You can do this with wpshell, a tool written by my fellow Automattician Apokalyptik. Although this is a fairly unknown and well hidden piece of code it’s worthy to install it on your local development environment in order to dive right into WordPress. After adjusting some basic configurations wpshell gives you a command shell that accepts native PHP code as well as all the functionality your regular WordPress install would give you. And there is even more, it also parses all the tokens and lets you grab information about function definitions, their parameters and the like.

If this got you excited go ahead and watch this video showing wpshell in action and how it is installed.

Before we get started, there are some requirements and warnings:

  • This is intended for advanced developers. If you don’t know what you’re doing you can easily mess up your WordPress install
  • Although possible, I would not run this on production, but only in a local development environment
  • You need to have a working installation of WordPress that will be utilized by wpshell

Here’s a quick walkthrough of the installation procedure:

  • svn co wpshell

    (check out the wpshell repository)

  • cd wpshell

    (get in the folder)

  • vi wpshell

    (adjust shell variable and 2 occurences of the PHP path to your needs )

  • vi wpshell-config.php

    (adjust HTTP_HOST, REQUEST_URI and other $_SERVER variables that might need adjustments to fit your WordPress install. You can easily check those values in your current WordPress installation. Adjust require statement to point to the wp-config.php of your WordPress install.)

If you did everything right you should now be able to use the shell. Here are some basics.

Invoking the shell:

  • wpshell

    will get you a command prompt. Here you can enter native PHP code or WordPress functions or functions defined elsewhere in your project

  • echo 'echo $blog_id' | wpshell

    will take the command(s) you pipe to the shell and execute them

  • wpshell < /path/to/a/php/script

    will use the php script as source for the commands

wpshell also comes with a bunch of built-in commands to make your life easier. Here are some of them

Database queries:

  • get_results $query

    returns the result of $wpdb->get_results

  • get_var $query

    returns the result of $wpdb->get_var

  • get_col $query

    returns the result of $wpdb->get_col

  • get_row $query

    returns the result of $wpdb->get_row


  • ls [path]

    list the content of the current directory

  • cd [path]

    change current working directory

  • quit

    quit the shell


  • d $function_name

    displays the function definition

  • f $function_name

    displays the function source

  • fsearch $search_string

    search for a function matching the search string in the current working directory

  • c $class_name

    returns the class source

  • csearch $search_string

    search for a class matching the search string in the current working directory

That’s all nice, but what can I do with it? – The sky is the limit.

I personally use it like this; I wrote a small Coda Plugin that takes selected content and executes it in wpshell and throws the result back to a new tab in my editor. In this way I can just mark code fragments or queries and run them against wpshell right away.
I also created a small PHP script together with an AppleScript that allows me to search for a function and open the file it’s defined in directly in Coda and jump to the correct line or alternatively perform a manual lookup and display the result in Coda.
If there is any interest I can make these scripts public as well. They are still very edgy though.
I also have a wpshell running inside a screen session and keep it always accessable via TotalTerminal.


I did not have much time to look into it, but the code is so awesome that I hope to integrate it better in my IDE. I’m planning to setup the parameters in wpshell-config.php automatically when I fire up a wpshell from within Coda. It would traverse upwards from the opened file until it finds a wp-config.php and setup HTTP_HOST and path accordingly. It could also work by simply entering a URL and Coda would fire up a preview window in Chrome along with the wpshell adjusted to exactly this url.

6 Responses to “Meet wpshell – the power of WordPress at your prompt”

  1. Seems interesting to try. Any idea if it can run on Windows? Seems to be set up for usage via bash.

  2. Feeling the love 🙂


  1. Meet wpshell – the power of WordPress at your prompt « danielbachhuber - November 15, 2011

    […] Meet wpshell – the power of WordPress at your prompt. wpshell is an undiscovered gem. Someone should lead a WordCamp talk about it and the secrets it holds. Like this:LikeBe the first to like this post. Published: November 14, 2011 Filed Under: asides Tags: advice : tips : tools : web development : WordCamps : WordPress : wpshell […]

  2. wpshell & debugging wordpress » Jon Kristian - November 29, 2011

    […] you are like me and feel more comfortable and in-control using the shell, you need to check it out: Easy to install and easy to use, It will be interesting to see how many different scenarios it […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: