Skip to content
Go to file
This branch is 92 commits ahead, 2 commits behind djcp:master.

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Gem Version

Build Status

This implements the WordPress XML RPC API as released in version 3.4.

WARNING: SSL is NOT enabled by default for ease of testing for those running OS X systems without setup SSL certs. If this is important to you, checkout the options for instantiating a new client where you can set :use_ssl to true.

Getting Started

Installing rubypress

System installation

gem install rubypress

Using Bundler

# Add this to your Gemfile
gem 'rubypress'

Using rubypress

In a script

require 'rubypress'

Usage Examples

Create a new client

wp = => "",
                           :username => "",
                           :password => "yourwordpresspassword")

Automatically retry timeouts

When creating the client, you can optionally pass :retry_timeouts => true to rescue Timeout::Error and Net::ReadTimeout errors and retry the call.

wp = => "",
                           :username => "",
                           :password => "yourwordpresspassword",
                           :retry_timeouts => true)

Non-standard xmlrpc.php location

NOTE: If your xmlrpc.php is not on the host root directory, you need to specify it's path. For example, to connect to

wp = => "",
                           :username => "",
                           :password => "yourwordpresspassword",
                           :path => "/path/to/blog/xmlrpc.php")

Making requests

(Based off of the WordPress XML RPC API Documentation)

Getting Options


# Returns a hash of options from the wp_options table
=> {"software_name"=>{"desc"=>"Software Name",

(just a small excerpt of actual options for the sake of the whole brevity thing)

Creating a new post

wp.newPost( :blog_id => "your_blog_id", # 0 unless using WP Multi-Site, then use the blog id
            :content => {
                         :post_status  => "publish",
                         :post_date    =>,
                         :post_content => "This is the body",
                         :post_title   => "RubyPress is the best!",
                         :post_name    => "/rubypress-is-the-best",
                         :post_author  => 1, # 1 if there is only the admin user, otherwise the user's id
                         :terms_names  => {
                            :category   => ['Category One','Category Two','Category Three'],
                            :post_tag => ['Tag One','Tag Two', 'Tag Three']

# Returns the newly created posts ID if successful
=> "24"  

Using SSL to connect

Use the default SSL port of 443

wp = => "",
                           :username => "",
                           :password => "yourwordpresspassword",
                           :use_ssl => true)

Use a non-default ssl port of your choosing (must be setup on your server correctly)

wp = => "",
                           :username => "",
                           :password => "yourwordpresspassword",
                           :use_ssl => true,
                           :ssl_port => 995)

Uploading a file

wp.uploadFile(:data => {
	:name => FILENAME,
	:type => MIME::Types.type_for(FILENAME).first.to_s,
	:bits =>

To make further requests, check out the documentation - this gem should follow the exact format of the WordPress XML RPC API. For even further clarification on what requests are available, take a look in the spec folder.

Contributing to rubypress

Pull requests welcome.

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
  • Fork the project.
  • Start a feature/bugfix branch.
  • Commit and push until you are happy with your contribution.
  • Make sure to add tests for it. This is important so we don't break it in a future version unintentionally.
  • Submit a pull request


Environment Variables

The test suite requires that the following environment variables are set:


Optionally, you can create a file in the working directory called .env and add the following to it:

or use the sample-dot-env file as a base. .env will not be committed. When RSpec runs it will set the environment variables for you. If you use a port other than 80, specify it with WORDPRESS_PORT and use WORDPRESS_USE_SSL=true for HTTPS servers. Be sure to set the port to 443 for standard HTTPS servers.

If you'd like to run the tests to test a server with plain HTTP authentication, use these environment vars:


The Basic Authentication settings also allow a custom port and whether to use SSL/HTTPS. Note that, like the host and path, these variable names include HTTP_ and can be set to the same or different values as needed.


  • Zach Feldman @zachfeldman - current maintainer, majority of codebase
  • Dan Collis-Puro @djcp - original project creator


  • Abdelkader Boudih @seuros (Removed deep_merge monkeypatch if ActiveSupport is defined, small refactors, fixed dependency issue with retry)
  • Alex Dantas @alexdantas (README edits re: host option)
  • Pacop @pacop (Added a far easier way to upload files than the default method chain)
  • David Muto @pseudomuto (Added ability to use a .env file and to retry failed requests)
  • Teemu Pääkkönen @borc (Added HTTP authentication and tests for it)
  • Brian Fletcher @punkie (Did work to try to get to 1.9.2 compat with tests, VCR issues prevented this. Now only officially support 1.9.3 and up)
  • Corey @developercorey (Added ability to change SSL port, README updates)
  • Michael @mibamur (Patched uploadFile method)
  • Rebecca Skinner @sevenseacat (Cached the XMLRPC connection to save resources)
  • Casey Hadden @caseyhadden (Added support for cookie-based authentication schemes)
  • Noah Botimer @botimer (Allowed custom prefixes on method names and tests to run against https servers on any port)
  • Carlos Pérez Cerrato @lastko (Caught Errno::EPIPE: Broken pipe errors)
  • Eric Gascoine @ericgascoine (Fixed getPostStatusList)
  • Matt Colyer @mcoyler (Added configurable timeouts)
  • Karim Naufal @rimkashox (Added support for Ruby >= 2.4.0)


Licensed under the same terms as WordPress itself - GPLv2.


Ruby interface for the WordPress XMLRPC API. Follows standard XML-RPC Documentation closely.



No releases published


You can’t perform that action at this time.