CLI for WordPress.org REST API v2

CLI to help test-drive the WordPress.org REST API.

Installing

1. WP-API v2 depends on the latest WordPress.org, so download it from Subversion.
2. Install WP-API plugin from Git and activate it.
   • There are some fixes that I made concerning file uploads and missing metadata, consider using the branch 'tnegri' of my fork if the fixes are not already merged.
3. Install Node.js.
4. Install the latest published version of this CLI on your system: npm install --global wp-api-cli.
5. Update CLI from API description: wp-api-cli update https://yoursite.com.

Authenticating with OAuth 1.0

1. Install WP-API/OAuth1 from Git to support OAuth authentication, activate it.

   • There are some fixes that I made concerning signature checking, consider using the branch 'tnegri' of my fork if the fixes are not already merged.

2. Install WP-CLI to generate OAuth keys.

3. Go to your WordPress installation folder and create a new consumer key and secret for this CLI:

   wp oauth1 add

4. Authenticate this CLI:

   wp-api-cli authenticate            \
       --oauth_key=CONSUMER_KEY       \
       --oauth_secret=CONSUMER_SECRET

5. It will ask for an authorization token. Follow the steps on the browser, copy the authorization token and paste it on console.

6. It will write the OAuth tokens to a file for further use -- this is a sensitive file, make sure to protect it!

7. When you execute a command, the CLI will look for the file to grab the OAuth tokens, you may set a different file to use with the option --oauth_file.

8. If you want to remove the OAuth tokens from the file system:

   wp-api-cli logout

Authenticating with HTTP Basic Auth

1. Install WP-API/Basic-Auth from Git to support HTTP Basic Authentication, activate it.
2. Use options --http_user and --http_pass with every request you make.

Commands

After installing the CLI, you need to update its definition:

wp-api-cli update https://example.com

After updating, ask for help to see everything available in your site:

wp-api-cli --help

Examples

Show all posts

$ wp-api-cli posts --table --project id,date,title

----------------------------------------------
 | id | date                | title         |
----------------------------------------------
 | 6  | 2015-08-22T20:27:32 | Hello, WP-API |
 | 1  | 2015-08-18T23:09:35 | Hello world!  |
----------------------------------------------

Show a specific post

$ wp-api-cli posts --yaml --id 6 --project id,date,title,content,comment_status

id: 6
date: '2015-08-22T20:27:32'
title:
  rendered: 'Hello, WP-API'
content:
  rendered: |
    <p>Hello, dear WP-API!</p>
comment_status: open

See docs/COMMANDS.md for a full documentation on commands.

Developers

This project is structured as follows:

1. index.js is the entry point, it executes the main function defined in lib/wp-api-cli.js.
2. lib/wp-api-cli.js wires everything up.
3. lib/wp-api.js contains the class that communicates with the REST APIs.
4. lib/modules.js loads all modules. A module is an object that provides the functionalities of the CLI.
   • lib/modules/attachment.js handles attaching files to requests, used to upload media.
   • lib/modules/auth.js handles authentication.
   • lib/modules/bool-loader.js handles boolean values in dynamic options.
   • lib/modules/describe.js let you fetch a description of the API.
   • lib/modules/dict-loader.js handles transforming options into objects (dict: prefix).
   • lib/modules/file-loader.js handles loading options from file (file: prefix).
   • lib/modules/insecure.js allows connection to insecure sites, e.g. with self signed certificates.
   • lib/modules/method.js sets which HTTP verb to use in request.
   • lib/modules/routes.js handles all dynamic commands and options based on actual API description (plus some helpers).
   • lib/modules/site.js lets you set which site the CLI connects to.
   • lib/modules/text-loader.js handles text: prefix.
   • lib/modules/update.js fetches API description and writes it to a file for further use by lib/modules/routes.js.
5. Files in lib/utils are utility functions to make coding easier.

If you want to create a new set of commands, drop a file in lib/modules and load it in modules.js. Full explanation in docs/MODULES.md.

Useful Links

• WordPress.org Subversion download
• WP-API project on GitHub
• Online documentation for WP-API v2
• WP-API/OAuth1 project on GitHub
• WP-API/Basic-Auth project on GitHub
• Node.js
• WP-CLI

Related Issues and Pull Requests

Issues

• WP-API/WP-API: API description for user creation

Fixes

• WP-API/WP-API: Fix file upload for attachments
• WP-API/WP-API: Fix MD5 check on file uploads
• WP-API/WP-API: Add missing 'force' arg to posts-terms DELETE
• WP-API/WP-API: Add missing 'force' argument to Users DELETE
• WP-API/WP-API: Add missing 'force' arg to Meta DELETE
• WP-API/WP-API: Fix typo in message
• WP-API/OAuth1: Fix signature check for sub-folder WP installs
• WP-API/OAuth1: Fix signature for params with special chars
• niallsmart/node-oauth-like: Fix signature with queryString

Features

• WP-API/WP-API: Add help properties to endpoint arguments
• WP-API/OAuth1: Add filter to signal error for WP-API v2

Project Overview