Unlocking the potential of the WP REST API at the command line
Unlock the potential of the WP REST API at the command line.
Warning: This project is at a very early stage. Treat it as an experiment, and understand that breaking changes will be made without warning. The sky may also fall on your head. Using RESTful WP-CLI requires the latest nightly build of WP-CLI, which you can install with
wp cli update --nightly.
Initial development was backed by a Kickstarter project. This project will evolve alongside the WP REST API's evolution in WordPress core.
As WordPress becomes more of an application framework embedded into the web, RESTful WP-CLI enables WP-CLI users to interact with a given WordPress install through the higher-level, self-expressed abstraction of how WordPress understands itself. For instance, on an eCommerce website, instead of having to know data is stored as
wp post list --post_type=edd_product, RESTful WP-CLI exposes the properly-modeled data at
wp rest product list.
Here's an overview of how RESTful WP-CLI works, in two parts.
Target a specific WordPress install with
# The `--path=` global parameter tells WP-CLI to interact with a WordPress install at a given path. # Because this is a stock WordPress install, you see the posts, pages, and other resources you'd expect to see. $ wp --path=/srv/www/wordpress-develop.dev/src rest usage: wp rest attachment or: wp rest category or: wp rest comment or: wp rest page or: wp rest page-revision or: wp rest post or: wp rest post-revision or: wp rest status or: wp rest tag or: wp rest taxonomy or: wp rest type or: wp rest user
--http=<domain>global parameter tells WP-CLI to auto-discover endpoints over HTTP.
Because Wired has some custom post types, they're automatically registered as WP-CLI commands.
$ wp --http=www.wired.com rest usage: wp rest attachment or: wp rest category or: wp rest comment or: wp rest liveblog or: wp rest liveblog-revision or: wp rest page or: wp rest page-revision or: wp rest podcast or: wp rest post or: wp rest post-revision or: wp rest series or: wp rest slack-channel or: wp rest status or: wp rest tag or: wp rest taxonomy or: wp rest type or: wp rest user or: wp rest video
--ssh=<host>global parameter proxies command execution to a remote WordPress install.
Because runcommand has a completely custom data model, you can only interact with commands, excerpts, and sparks.
$ wp --ssh=runcommand.io rest usage: wp rest command or: wp rest excerpt or: wp rest spark
In addition to the standard list, get, create, update and delete commands, RESTful WP-CLI also registers commands for higher-level operations like
# In this example, `@wpdev` is a WP-CLI alias to `--path=/srv/www/wordpress-develop.dev/src`. $ wp @wpdev rest user usage: wp rest user create --username= [--name=] [--first_name=] [--last_name=] --email= [--url=] [--description=] [--nickname=] [--slug=] [--roles=] --password= [--capabilities=] [--porcelain] or: wp rest user delete [--force=] [--reassign=] [--porcelain] or: wp rest user diff  [--fields=] or: wp rest user edit or: wp rest user generate [--count=] [--format=] --username= [--name=] [--first_name=] [--last_name=] --email= [--url=] [--description=] [--nickname=] [--slug=] [--roles=] --password= [--capabilities=] [--porcelain] or: wp rest user get [--context=] [--fields=] [--field=] [--format=] or: wp rest user list [--context=] [--page=] [--per_page=] [--search=] [--exclude=] [--include=] [--offset=] [--order=] [--orderby=] [--slug=] [--roles=] [--fields=] [--field=] [--format=] or: wp rest user update [--username=] [--name=] [--first_name=] [--last_name=] [--email=] [--url=] [--description=] [--nickname=] [--slug=] [--roles=] [--password=] [--capabilities=] [--porcelain]
wp rest * editto open an existing item in the editor.
$ wp rest category edit 1 --user=daniel
description: name: Uncategorized slug: uncategorized parent: 0
wp rest * generateto generate dummy content.
$ wp @wpdev rest post generate --count=50 --title="Test Post" --user=daniel Generating items 100% [==============================================] 0:01 / 0:02
wp rest * diffto diff a resource or collection of resources between environments.
If WP-CLI is operating directly against a WordPress install, you can use the
--debugflag to track the number of queries and total execution time. This can be useful for measuring and profiling API requests.
$ wp rest category list --debug Debug (rest): REST command executed 3 queries in 0.000311 seconds. Use --debug=rest to see all queries. (1.118s)
There are many things RESTful WP-CLI can't yet do. Please review the issue backlog, and open a new issue if you can't find an exising issue for your topic.
Installing this package requires WP-CLI 1.3.0-alpha or greater. Update to the latest nightly release with
wp cli update --nightly.
Once you've done so, you can install this package with
wp package install wp-cli/restful.
We appreciate you taking the initiative to contribute to this project.
Contributing isn’t limited to just code. We encourage you to contribute in the way that best fits your abilities, by writing tutorials, giving a demo at your local meetup, helping other users with their support questions, or revising our documentation.
For a more thorough introduction, check out WP-CLI's guide to contributing. This package follows those policy and guidelines.
Think you’ve found a bug? We’d love for you to help us get it fixed.
Before you create a new issue, you should search existing issues to see if there’s an existing resolution to it, or if it’s already been fixed in a newer version.
Once you’ve done a bit of searching and discovered there isn’t an open or fixed issue for your bug, please create a new issue. Include as much detail as you can, and clear steps to reproduce if possible. For more guidance, review our bug report documentation.
Want to contribute a new feature? Please first open a new issue to discuss whether the feature is a good fit for the project.
Once you've decided to commit the time to seeing your pull request through, please follow our guidelines for creating a pull request to make sure it's a pleasant experience. See "Setting up" for details specific to working on this package locally.
GitHub issues aren't for general support questions, but there are other venues you can try: https://wp-cli.org/#support
This README.md is generated dynamically from the project's codebase using
wp scaffold package-readme(doc). To suggest changes, please submit a pull request against the corresponding part of the codebase.