RESTful WP-CLI – The journey begins

This post originally appeared on the WP-CLI blog.

And so the journey begins. As with most journeys, I have a mixture of emotions: excitement, anticipation, trepidation, and eagerness. Although the destination may be far away, I know I can get there as long as I consistently take steps in the right direction.

Today marks the formal kickoff of my Kickstarter project, “A more RESTFul WP-CLI”. To celebrate the occasion, I’ve launched a project page to capture high-level goals and document my progress along the journey. I’ll keep it updated as I write blog posts every couple or few weeks. Consider these blog posts both a development log and an invitation to participate — I look forward to your comments, issues and pull requests.

For the past month or so, the question at the top of my mind has been: what does it mean to “unlock the potential of the WP REST API at the command line”? Or, even more broadly, why do this project?

These are big questions, and I consider myself fortunate to be able to explore them over the next six months or so. Here’s how I’ve unpacked them so far, in a series of loosely connected ideas:

• WP-CLI’s goal is to be, quantitatively, the fastest interface for developers to manage WordPress. For anything you want to do with WordPress, using WP-CLI should save you multitudes of time over doing it some other way.
• WP-CLI and WP REST API both offer CRUD interfaces to WordPress resources. wp post list is more or less GET /wp/v2/posts. But, wp widget list doesn’t yet have an equivalent in WP REST API. We still have a ton of work to do.
• Building the WP REST API has been, and will continue to be, an exercise of modeling how WordPress works to a consistent (RESTful) interface. Furthermore, this model is declared in a common language for clients to interpret.
• At some point in the future, WP-CLI will be able to ditch a substantial amount of its internals when it can use the WP REST API as its interface to WordPress. WP-CLI can continue to serve as the fastest way for developers to manage WordPress, offering higher-level meta operations like generate, (push|pull), and clone in addition to being a seamless command line interface to WordPress internals.
• As WordPress developers write new endpoints for the WP REST API, it will be quite powerful to have those endpoints instantly accessible through the command line, and as accessible as core resources. For instance, where WP-CLI currently has the wp post * commands, WP-CLI requires Easy Digital Downloads to produce its own wp edd * commands.
• It appears to be supremely possible to deliver this project as a series of improvements to WP-CLI, shipped over one or more versions in the next couple of quarters.

Lots of threads to pull on.

I’m starting development by working towards making wp tag list work interchangably with local and remote sites. Doing so already raises a few issues:

• WP-CLI needs to be easier to register commands on the fly. In my prototype, I had to eval() a dynamically generated class. It would be much nicer to be able to register an arbitrary function, closure, or method as a WP-CLI command.
• When we register REST endpoints to WP-CLI on the fly, there’s the potential for them to conflict with existing commands. Furthermore, the endpoints will vary from site to site. Ideally, the commands you see should represent the commands available on the target site. I think site aliases may offer us a backwards-compatible implementation; for instance, specifying an alias like wp @prod would only expose commands available on production.
• Remote calls will need authentication. Ideally, it should be possible to authenticate once through a supported protocol (basic, oAuth1, API key, etc.), and store these authentication details somewhere on the file server. This is potential rationale for a config management command. If you aren’t blocking web requests to wp-cli.yml and wp-cli.local.yml already, you should be.