WP CLI Tools

Collected command line utilities for posting, updating, and working with a WordPress blog. These tools grew out of a series of posts on using Lua to build a simple tool for posting from the command line.

The Tools

All of these tools are designed for use at the command prompt or from scripts and batch files. They save some configuration details in a common configuration file (which includes the current authorization token, so don’t publish your configuration file) and have a a number of common command line options.

In all cases wpxxx --help will print some helpful text along with a full list of the command line options.

WPGet

Get a post, page or media item from the blog, along with metadata about the item.

C:>wpget.lua --help
Retrieve a WordPress blog post to a file or stdout. Part of the WP CLI Tools.

WP CLI Tools


These options are related to the config file, with the ones marked * actually
stored in the file. Either --blog or --site and --token must be available and
consistent for posting to be allowed.
  --authenticate              Do web-based authentication and write config
  --blog (default "")         *The blog at which to post.
  --token (default "")        *The OAuth token from the redirect URL.
  --expires (default "")      *The OAuth token expiration date.
  --site (default "")         *The WP Site ID for the token's blog.
  --tokenurl (default "")     The full URL containing the token
  --showconfig                Just display the config file
  --writeconfig               Write the config file with the options

General options:
  -v,--verbose                Be more chatty about the process
  --keepraw (default "")      Name a file to fill with raw logging
  --debug                     Don't use this.

Options for the blog post itself:
  --ID (number)               The post ID to get.
  --media                     Get media not post.
  --out (default stdout)      The file to write.
  --container                 Save the whole JSON container, not just the file.

WPList

List various tables related to a blog. Specifically, lists posts, media, categories, and tags.

C:>wplist.lua --help
List information from a WordPress blog to a file or stdout. Part of the WP CLI Tools.

WP CLI Tools


These options are related to the config file, with the ones marked * actually
stored in the file. Either --blog or --site and --token must be available and
consistent for posting to be allowed.
  --authenticate              Do web-based authentication and write config
  --blog (default "")         *The blog at which to post.
  --token (default "")        *The OAuth token from the redirect URL.
  --expires (default "")      *The OAuth token expiration date.
  --site (default "")         *The WP Site ID for the token's blog.
  --tokenurl (default "")     The full URL containing the token
  --showconfig                Just display the config file
  --writeconfig               Write the config file with the options

General options:
  -v,--verbose                Be more chatty about the process
  --keepraw (default "")      Name a file to fill with raw logging
  --debug                     Don't use this.

Options identifying what to list:
  --list (default "posts")    List: posts, categories, tags, media, users,
                              comments, stats. Some need --container to be
                              useful.

Options for the listing:
  -n,--number (default 20)    Items per page
  -p,--page (default 1)       Page to retrieve
  --before (default "")       Posted before ISO8601 date
  --after (default "")        Posted after ISO8601 date
  --order (default "DESC")    Sort order: DESC or ASC
  --orderby (default "date")  Column to sort by: date, modified, comment_count, ID.
  --type (default "post")     Type: post, page, any.
  --tag (default "")          Tag name to list
  --category (default "")     Category name to list
  --status (default "")       Status to list
  --out (default stdout)      The file to write.
  --container                 Save the whole JSON container, not just a simple list.

WPPost

Create a new post and optionally save its metadata.

C:>wppost.lua --help
Post a file on a WordPress blog as a draft post. Part of the WP CLI Tools.

WP CLI Tools


These options are related to the config file, with the ones marked * actually
stored in the file. Either --blog or --site and --token must be available and
consistent for posting to be allowed.
  --authenticate              Do web-based authentication and write config
  --blog (default "")         *The blog at which to post.
  --token (default "")        *The OAuth token from the redirect URL.
  --expires (default "")      *The OAuth token expiration date.
  --site (default "")         *The WP Site ID for the token's blog.
  --tokenurl (default "")     The full URL containing the token
  --showconfig                Just display the config file
  --writeconfig               Write the config file with the options

General options:
  -v,--verbose                Be more chatty about the process
  --keepraw (default "")      Name a file to fill with raw logging
  --debug                     Don't use this

Options for the blog post itself:
  --title (default "")        The post title. Defaults to the file name.
  --tags (default "")         Comma separated list of tags to apply.
  --category (default "")     Comma separated list of categories to apply.
  --colophon (default "")     Text appended (after a blank line) to the post.
  --container                 Save the file's container.
  --out (default stdout)      The file to write.
  <filename> (default "")     The file to post.

TODO: Also support updating an existing post, as well as posting with status other than draft.

Authorization

All of the WP CLI Tools share a common configuration file and authorization token. The token is specific to one blog, and is obtained by using the common --authenticate option to any of the tools. With that option, the tool will open the user’s browser on the authentication page at WordPress.com where the user gets to select the blog to control and grant permission. Once permission is granted, the tool is given the token and stores it away. Tokens obtained this way are currently good for 2 weeks.

This implies that in order to use the WP CLI Tools, you must have a web browser set up as the default browser on the PC which will be using the tools. Naturally that PC has to also have an internet connection available.

Deprecated tools

WPPost over XML-RPC

The first complete version used the XML-RPC API, which requires that the script know a username and password. It works well enough to create a new draft post from a Markdown file, but it still stores a password on your PC and that is never the best idea.

A moderate mitigation of the risk of a stored password can be had by enabling Two Factor Authentication for your WordPress.com account, and then generating an Application Password just for the use of WPPost. See my recent post about setting this up for more details.

Source Code

Source code (and revision history) for the complete set of tools is in a public fossil repository.

Fossil

Fossil

Fossil is a distributed version control system. It has a number of properties that make it attractive, especially for smaller projects with few developers. Its key feature is that it is designed from the core out to be low overhead and low ceremony. That combined with it being free and open source means that its total cost of ownership for a typical project really is very small.

In addition to source code management, it also provides wiki and a trouble ticket tracking system, and it has the ability to act as a web server for both the repository content and a user interface to make configuration easier.

On most platforms, fossil is a single executable file that needs no formal installation to be useful. Just put fossil.exe (or your platform’s equivalent) in your PATH and try fossil help to demonstrate that it is happy.

Fossil uses the well respected SQLite database engine to manage the storage of the local copy of each repository. This makes a local repository be a single file that itself is easy to manage.

If you just want to play with the WPCLI tools without first installing fossil, you can retrieve a ZIP from the public repository: log in as anonymous, click Timeline, any version (the most recent is likely the best starting point), and then either the “Tarball” or “ZIP Archive” links to taste.

Lua

Lua

Lua is a small, fast, and powerful scripting language. While it was originally designed for data description and application extension, it has grown up to be a decent first class language in its own right.

It is still remarkably easy to embed in larger applications, and can be found in the wild in many video games, in Adobe Photoshop Lightroom (where Lua code makes up well more than half of the source kit, apparently), and many other unexpected places.

  • The official Lua home page has links to the community, documentation, and source code for all officially released versions of Lua.
  • Lua Binaries is the official source of pre-built Lua interpreters.
  • Lua for Windows is showing its age, and limited to Lua v5.1, but it remains the only trivial to install and use distribution of Lua along with useful third party modules for Windows machines.
  • The [Lua users wiki binaries page] has lists of places to find binaries for lots of platforms
  • The LuaDist project is trying to become a distribution and package management system for Lua and supporting modules. It will be the likely successor to Lua for Windows once they chase a few more issues out.

ZeroBrane Studio

ZBS

While not strictly necessary, a decent IDE and debugger can make working with Lua easier. Any plain text capable editor (even Notepad) is sufficient for simple scripts. But beyond the “hello, world” level, support for code coloring, word completion, code analysis, and debugging becomes extremely valuable.

Lua for Windows includes a decent editor named SciTE that supports Lua well (and can even be extended with Lua).

But the industrial strength and yet free 800 pound gorilla is turning out to be Paul Kulchenko’s ZeroBrane Studio. It not only provides a clean text editor with code coloring, word completion, and syntax hints, but it also provides a debugger that can be connected to nearly any application that embeds Lua and in many cases can even be used to do live coding where scripts can be changed while the application is running.

Others

One advantage of building tools in a scripting language is that you don’t need elaborate tool chain suites containing compilers and debuggers that fill up many MB of downloads just to play around. For serious work, those will be needed and we generally recommend the GNU Compiler Collection which are ported to many platforms. In most cases, however, you should use the actual compiler used to build your platform’s installation of Lua unless you are also planning to fold the Lua core into your project.

Getting Started

To get started you will want to do some or all of the following:

  1. Get the latest version of fossil from
  2. Install it in Windows by simply putting fossil.exe in a folder on your PATH. You will be using it from a command prompt, so if you’ve edited the system PATH to do this, you will want to restart any open command prompts so they are current.
  3. Create a working folder somewhere. Inside your My Documents folder is fine. We’ll assume it is C:\Users\You\Documents\wpcli, but it really could be anywhere. Open a command window and cd to that folder.
  4. Clone the repository with a command like this:
    fossil clone http://chiselapp.com/user/rberteig/repository/WPCLI wpcli.fossil
  5. Open the repository in some folder so you can see its content and work with it. The easiest folder to use is the one you are standing in right now, and that is both safe and reasonable: fossil open wpcli.fossil
  6. You now have a tree of files rooted in the current folder. The wprpcxml folder has the version that we abandoned after [part 3][p3]. The wprest folder has the version based on the REST API.

Keeping up to date

Later you will want to update that working copy to track changes made in the public repository. That is easy to do: with an open command window, cd into the working folder, then say fossil update.

Keeping track of your own changes

If you make changes that you want to preserve, you can use a private branch which will prevent fossil from attempting to synchronize them back to the public repository. To do this, just use the command:

fossil checkin --private --branch mywork

for your first checkin. That will move your open working folder on to the private branch named mywork. Later, after a fossil sync, fossil pull, or fossil update has brought down changes from the public repository you want to include, you can use the command fossil merge trunk to bring them into your branch.

Contributing changes to our repository

Email us and describe what you’ve done. We will be happy to set up developer access to the repository on request.

Posts about the Tools