restful

by wp-cli

wp-cli /restful

Unlocking the potential of the WP REST API at the command line

132 Stars 13 Forks Last release: 3 months ago (v0.3.0) MIT License 193 Commits 3 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

wp-cli/restful

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.

Build Status

Quick links: Using | Installing | Contributing | Support

Using

RESTful WP-CLI makes WP REST API endpoints available as WP-CLI commands.

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.

1. Auto-discovers WP REST API endpoints from any WordPress site running WordPress 4.7 or higher

Target a specific WordPress install with

--path=
,
--ssh=
, or
--http=
:
# 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 

The --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

The --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

2. Registers WP-CLI commands for the resource endpoints it understands, in the
wp rest
namespace.

In addition to the standard list, get, create, update and delete commands, RESTful WP-CLI also registers commands for higher-level operations like

edit
,
generate
and
diff
.
# 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]

Use wp rest * edit to open an existing item in the editor.

$ wp rest category edit 1 --user=daniel

description: name: Uncategorized slug: uncategorized parent: 0

Use wp rest * generate to generate dummy content.

$ wp @wpdev rest post generate --count=50 --title="Test Post" --user=daniel Generating items 100% [==============================================] 0:01 / 0:02

Use wp rest * diff to diff a resource or collection of resources between environments.

$ wp @dev-rest rest command diff @prod-rest find-unused-themes --fields=title (-) http://runcommand.dev/api/ (+) https://runcommand.io/api/ command:

  • title: find-unused-themes

If WP-CLI is operating directly against a WordPress install, you can use the

--debug
flag 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)
+---------------+
| name          |
+---------------+
| Test Category |
| Uncategorized |
+---------------+

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

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
.

Contributing

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.

Reporting a bug

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.

Creating a pull request

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.

Support

Github issues aren't for general support questions, but there are other venues you can try: http://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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.