wordpress CLI





blogpost – WordPress blog client




A WordPress command-line blog client. It creates and updates blog entries directly from AsciiDoc, Rimu Markup or HTML source documents. You can also delete and list blog entries from the command-line.

  • Manages WordPress Posts and Pages.
  • Automatically uploads media files (images, video, audio).
  • Only posts new or modified content and media files.
  • Manages WordPress blog categories.


cat, categories

Specify the –categories option and either a BLOG_FILE or a –post-id to set the post’s categories. If the –categories option is not specified then all blog categories for all posts are listed.

d, delete

Delete blog post. Deletes the BLOG_FILE blogpost cache file but not the BLOG_FILE.


Convert the BLOG_FILE to HTML and print on stdout.

i, info

Print blog post information. Information is sourced from the client-side BLOG_FILE blogpost cache file.

l, list

List recent blog Posts. Information is sourced directly from WordPress server. Use the –pages option to list published Pages.

p, post

Post the BLOG_FILE to the blog. If this is the first time the BLOG_FILE has been posted a new post is created, otherwise the existing post is updated.


-a, –attribute=ATTRIBUTE

Set asciidoc(1) attribute value. Identical to asciidoc(1) –attribute option. This option may be specified more than once. Applicable to post command.


A single asciidoc(1) option. This option may be specified more than once.

-c, –categories=CATEGORIES

A comma separated list of categories that will be assigned to the blog post. Prefixing CATEGORIES with a plus or minus character adds or removes the categories from an existing post. Category names are case insensitive. If an assigned category does not already exist it will be created. Applicable to categories and post commands.

-d, –doctype=DOCTYPE

Specifies the type of AsciiDoc BLOG_FILE. Allowed values are AsciiDoc document types: article, book or manpage. The default document type is article.

-f, –conf-file=CONF_FILE

Use blogpost configuration file CONF_FILE. This file is read after the (optional) implicit $HOME/.blogpost configuration file.


Force blog file to upload even if it has not been modified since the last update command.


Force media files to upload even if they have not been modified since the last update command.

-h, –help

Show this help message and exit.


Specifies a comma separated list of one or more blog parameters that must be defined in the BLOG_FILE. If this option is not present then BLOG_FILE attribute parameter definitions are optional. See the ATTRIBUTE PARAMETERS section. Applicable to post command.


The name of the directory containing those media files that have URLs with relative path names. Defaults to the same directory as the BLOG_FILE. The media file path is generated by joining MEDIA_DIR with the relative path name.

-M, –no-media

Do not upload media files. Applicable to post command.

-n, –dry-run

Simulate command execution without doing anything, instead report what would have been done.

-p, –pages

Apply COMMAND to blog Pages rather than normal blog Posts. Applicable to delete, list and post commands.


Explicitly specify the blog post ID number. This option will only be necessary when there is no client-side BLOG_FILE cache file. Applies to delete and update commands.


Send WordPress XML-RPC via proxy server URL.

-t, –title=TITLE

Set the blog post title. Applicable to post command.

-u, –unpublish

Set blog post status to unpublished. Applicable to post command.

-U, –publish

Set blog post status to published. Applicable to post command.

-v, –verbose

Print more information about the actions being performed to stdout. Specifing this option twice to view asciidoc(1) verbose output.


Show program’s version number and exit.

blogpost saves the values set by the following options in the BLOG_FILE blogpost cache file: –doctype, –doctype, –pages, –post-id, –publish, –unpublish and –title. This means that once a blog post has been created you won’t need to use them in subsequent commands unless you decide to change them.


The BLOG_FILE is either an AsciiDoc formatted text file; a Rimu Markup text file or an HTML file. blogpost(1) uses asciidoc(1) and rimuc(1) commands to convert AsciiDoc and Rimu Markup blog files to WordPress compatible HTML.

Rimu Markup files must have a .rmu file name extension; HTML files must have a .html or .htm extension; all other files are assumed to be AsciiDoc formatted.

You can insert a WordPress more tag in an AsciiDoc blog file using the AsciiDoc block passthrugh macro:


You can put the more tag in a Rimu Markup blog file verbatim:


Be aware that WordPress does not handle all HTML tags, this is not an issue with the AsciiDoc or Rimu Markup blog files because the generated HTML is WordPress friendly.


Blogpost allows the following blog parameters to be defined inside an AsciiDoc or Rimu Markup BLOG_FILE: categories, status, title, doctype, posttype. The parameters are defined using AsciiDoc attribute entries or Rimu Markup macro definitions — the parameter name is prefixed with blogpost-.

AsciiDoc examples:

:blogpost-status: published

:blogpost-categories: blogpost,AsciiDoc,Blog client,WordPress


Blogpost attribute entry values are not subject to the usual AsciiDoc attribute substitution.

Equivalent Rimu Markup macro definitions:

{blogpost-status} = ‘published ‘

{blogpost-categories} = ‘blogpost,AsciiDoc,Blog client,WordPress’

The –mandatory-parameters option is used to make selected BLOG_FILE attribute entries mandatory. Example:


Parameter precedence is (from highest to lowest):

  1. Command-line options.
  2. BLOG_FILE entries.
  3. Blogpost cache.

Blog parameter name

Attribute name

Allowed values



Comma separated list of blog category names (see –categories option).



article, book or manpage (see –doctype option).



post or page (see –pages option).



published or unpublished (see published and –unpublished options).



Blog title (see –title option).

blogpost(1) automatically creates the blogpost AsciiDoc attribute which is useful for conditionally processing AsciiDoc document content.

blogpost(1) automatically uses the AsciiDoc title if neither the –title option or the blogpost-title attribute is defined and the title is not in the cache file.


You can upload media files to the WordPress server using XML-RPC but there is currently no way to programmatically list or delete media files held on the server. Blindly uploading new copies to the server every time the document is updated is an unacceptable.

To overcome this problem blogpost retains information about previously uploaded media (source paths, server URLs and media file MD5 checksums) in client-side per-document cache files. Cache files are stored in the same directory as the source BLOG_FILE but with .blogpost file name extensions. A document’s cache file is read before blogpost runs a command and is updated after running the post command. The delete and reset commands delete a document’s cache file.

blogpost uses cache files to ensure only new or modified media files are uploaded to the WordPress server. Because the caching is on a per-document basis, media files are not shared between documents.

In addition to storing media metadata, blogpost cache files also store the blog post ID, URL, title, creation and update timestamps along with the last used value of many of the blogpost command options. This is very handy, it means you don’t have to remember the blog post ID or the options you used to create the blog when you rerun the post command.


The generated HTML content is scanned for HTML anchor (a) and image (img) tags, if these tags refer to local media files then they are processed as follows:

  • The BLOG_FILE cache (see METADATA CACHING) is checked to see if the media file has been previously uploaded, if it has then the media file is checked (using an MD5 checksum) to see if it has changed.
  • If the media file is new or has changed then it is uploaded to the server.
  • Finally the media file reference in the HTML content is replaced with the server URL of the uploaded media file.

You can disable media processing with the –no-media option.

Allowable media file types are: gif, jpg, jpeg, png, pdf, doc, odt, mp3, ogg, wav, m4a, mov, wmv, avi, mpg. Note that not all WordPress servers support all media file types, if you get an Invalid file type the file type is not supported — check with your WordPress hoster, they may have upgrade options which will allow you to upload.


There are two types of WordPress content, Posts and Pages. A Post is the WordPress term for a regular blog entry whereas a Page (sometimes called a static page) is an entry that lies outside the normal blog chronology. WordPress manages Posts and Pages separately — use the –pages option to differentiate between the two. See for a detailed explanation.


Create, list, update and delete a blog post: post blogging_with_asciidoc.txt info blogging_with_asciidoc.txt list post blogging_with_asciidoc.txt delete blogging_with_asciidoc.txt


Mercurial repository:

Python WordPress library:


Rimu Markup:


Written by Stuart Rackham, <>