Wpcmd documentation

For version 0.05

Table of contents

What is wpcmd

Wpcmd is a command line client for WordPress blogs. The whole program is written in Python. It should work on every platform with an available Python interpreter.

Wpcmd is Free Software, licensed under the terms of the GNU General Public License, Version 2 or any later version of your choice.

The most important function of the program is to send a text as posting to a WordPress blog. This enables you to write posts in your favorite editor and publish them with a simple command. If you use a programmable editor, you can arrange things in a way allowing you to publish from your editor directly.

It may be unneccessary for those, who can do anything they want with the embedded WYSIWYG editor in WordPress and are comfortable with it. But for people, who prefer more to work with familiar tools than with a WordPress backend, which is often a little slow and clumsy, wpcmd is advantageous. The same is valid for any WordPress user, who wants to do scripted blogging tasks, especially, if the task can not be done by a WordPress plugin in an easy way.

For those who are connected to the internet via a modem or ISDN and for those, who have to pay for the duration of their internet connection and want to write their postings offline for that reason, wpcmd is useful too.

With wpcmd you can add blogging functionality to any other software which allows you to execute external programs in a macro or a script.

Wpcmd isn't only a program for the "normal" bloggers, but an utility for the so called "power users" too. Of course, wpcmd makes it possible to configure and use as many different blogs as you want.

Requirements

Wpcmd is build on top of a relatively recent version of the XMLRPC-API of Wordpress and works only with modern versions of WordPress. With WordPress 3.23 and with the WordPress-MU version currently used at wordpress.com, you will not encounter any problem.

You need a relatively recent version of the Python interpreter, because wpcmd utilizes some fresh features in Python. I tested my code with Python 2.7.3 only, but it should run with 2.6 too. Wpcmd does not work out of the box with Python 3.x or higher. Because the major Linux distributors still use 2.7.x as standard, I don't made the adjustments necessary to make wpcmd work with Python 3.

Installation

On unixoid platforms you can use the Makefile. Just invoke make, get root privileges and invoke make install to install wpcmd to /usr/local.

For other platforms I can't give instructions for installation. Please refer to your platform-specific Python documentation to get some information. In its current version, wpcmd should be able to run on MacOS, Windows and all Unices.

Blog configuration

Before you can post with wpcmd, you have to configure your blogs in wpcmd. To do this, invoke the following command in your shell:

      $ wpcmd -A
    

(That $ here and in all the following text means your shell prompt.)

Now wpcmd interactively requests a name for your blog, your blog account information and a comment for this blog configuration. If you want to identify your blog with the name Example and if your blog is available at blog.example.com, your configuration looks similar to the following:

      Name of the blog: Example
      Username: testloginname
      Password: testpassword
      Blog URL: blog.example.com
      Comment: Some words about this blog
    

Notice: Do not use spaces in your blog name. Select a short and mnemonic name for your blog.

After you completed your entries, wpcmd tries to get all needed informations from the WordPress installation. If wpcmd fails, you have made a tpyo in your specified data. On success you can use your freshly configured blog with wpcmd.

(In all following examples I will refer to this example configuration. Of course, you'll use your own configuration.)

Changing passwords

Of course you will change your WordPress password sometimes. But after you had changed your WordPress password, wpcmd needs to know the new password. To set a new password in wpcmd, type the following:

      $ wpcmd -P Beispiel
    

You are prompted for the new password, and after wpcmd verfied that it can log in with the new password, it will be stored for future usage.

Basic usage

To write a new post, just use your favorite editor. The file you have to write is easy to understand:

      !!blog: Example
      !!type: post
      !!categories: Test, XMLRPC, Wpcmd
      !!tags: Example, Techstuff
      !!title: My first post with wpcmd

      This is the text I want to post. It can simply be written in an
      editor.

      Paragraphs are marked by an empty line. For normal authoring,
      no HTML is required, but if I want it, I <em>can</em> use it.

      Funny, nerdy stuff!
    

Those lines starting with !! are instructions for wpcmd. They specify some meta information for the post. You can write them anywhere you like in the file, yes, you can even intermix them with the text, but I prefer to keep them at the top of the text.

With one important exception, there is no specific requirement on the order of the meta lines. The exception is, that the first line has to be the specification of the blog with !!blog:. If other meta lines preceed this specification, wpcmd will give an error message and exit.

If you save this file as example.txt, you can publish your post with the following command:

      $ wpcmd example.txt
    

Of course it is easy to do blogging with a script and wpcmd, and perhaps this is the thing you need. If you do scripting, you can skip the creation of a file; just use a minus-sign (-) as filename, and wpcmd reads its input from the standard input. This way, you can blog in a pipe.

Templates

It isn't exactly fun, always to write the !!-lines and have to remember the names of the blog's categories. Wpcmd can create templates for your blog posts. If you invoke the following command...

      $ wpcmd -T Example
    

...wpcmd creates a file Example-Post.txt, which is filled with the meta-lines. The categories are filled, and you can simply delete the unwanted ones.

These files are good candidates for the template directory of your favorite desktop system, to make the creation of posting-files fast and easy.

By the way: The -T option interprets an asterisk as a wild card for any sequence of characters, to allow the creation of many templates with one command. By typing wpcmd -T "*", you can create a template for all your configured blogs. But if you want a line beginning with # – this is sometimes wanted to post source – you have to start it with ##.

Character encoding

If you look in a created template file, you will notice a line like the following near the head of the file:

      # -*- coding: utf-8 -*-
    

This line specifies, which character encoding is used for your file. If you give such a line, wpcmd will convert the encoding before your text is published. This empowers you, to write your posts on systems with other character encodings, if you specify the used encoding.

By the way: Every line starting with # as first character is a comment line for wpcmd and ignored in processing. If you work in a way, that you write comments while creating your texts, you will like it.

Images and files

Frequently you want to embed images and other files in a post, which must be uploaded. Wpcmd does this with a minimum of new syntax, but you have to write a little HTML in your posts.

If you target a HTML-link <a href ...> to a local stored file or give a local file as source for an HTML-image <img src ...>, wpcmd uploads these files and changes the given file path to the file paths on the web server.

A short example:

      !!blog: Example
      !!type: post
      !!categories: Test, Upload
      !!tags: Upload, Techstuff
      !!title: My first upload with wpcmd
      
      Additional informations <a href="example.pdf">are available as
      PDF-File</a>.

      <img src="exmaple.jpg" />
    

If you publish this post, wpcmd checks for the existance of these two files. If they do not exist, you get an error message, which is better than an incomplete posting. But if the files do exist, the will be uploaded before the post is published and the paths in your post will be modified to reflect the location of the files on the server.

For specification of file you can use absolute or relative paths.

If ever you link something with a specified protocoll (mostly with http:, your link or image will be posted unchanged.

Multi-blog postings

You can configure as many blogs as you like in wpcmd, and sometimes you may wish to send a posting to more than just one blog. This is easy to do with wpcmd, you can specify as many blogs as you like for a file. All meta-lines following !!blog do refer to that blog's configuration.

If you have an additional blog Example2 configured, not only Example, the following post will be posted to both blogs.

      !!blog: Example
      !!type: post
      !!categories: Test
      !!tags: Double-post, Techstuff
      !!title: An example of a double post
      !!blog: Example2
      !!type: post
      !!categories: Backup
      !!tags: Gaga
      !!title: This does not make sense

      This posting will appear in two different blogs.
    

This is the reason why the !!blog-line must be always the first meta line. It defines a context for the following meta specifications.

Wpcmd-shell

If you invoke wpcmd without arguments, you'll see an interactive command line interpreter. This CLI empowers you to do administrative tasks on your wpcmd configuration and on your configured blogs.

This feature is still in development and therefore undocumented. In following versions of wpcmd, you will get here some possibility to do administrative tasks on your configured blogs, especially comment administration.

(I do hate the current WordPress dashboard, and that's my motivation to develop wpcmd!)

Feel free to play with this interface, if you want it. In the CLI, you can modify your wpcmd configuration in a way not possible via direct command invocation. The wpcmd shell comes with an integrated help system. Just type help.

Further information

A complete documentation of the options for the wpcmd command you find in the manual page of wpcmd, which you can read with man wpcmd.

Copyright

Copyright ©2009-2012 wpcmd Elias Schwerdtfeger, www.tamagothi.de

Wpcmd is Free Software, licensed under the terms of the second version of the GNU General Public License, or at your option, any later version of the GNU GPL. There is no warranty for this program. For details read the license text, which is part of the downloaded package and named COPYING.

Support

If you like wpcmd and you want to support me and the future development of the program, you can make me a donation via PayPal at my home page. Just look in the sidebar for the element titled "Spende", which is the german word for "donation". The word "Währung" means "Currency" in english, and "Betrag" is the "Amount".

I am a homeless german artist, living by begging and giving all my work for free in the hope that something will come back to me. It may sound naive, but I simply can't live another way.

And if you visit my home page, feel free to look at and eventually download the things given there for free. That's the reason why there are there.