File: README — Documentation for oz (0.1.1)

# # oz. # a command line t # u # by. m # chris wanstrath b # l # - and - e # r # dayne broderson #

New to ozimodo 1.2 is oz, the swiss army knife of command line tumbling.

Sure, Ajax is great. And you know what? Some HTML is okay, too. But nothing beats the warm glow of a terminal.

First, let us install oz. It’s pretty easy, thanks to Ruby and all the people who make it great:

$ gem install oz

(If you already have ozimodo 1.2 you can find oz in ozimodo/bin, but the gem install is recommended.)

The Wizard of oz

Not every tumblelog (or blog) supports oz yet, but they will. In the meantime, let’s play some with a tumblelog we know supports oz: ozmm.org.

$ oz --at ozmm.org commands

This will give us a list of commands ozmm.org’s API supports. I get this list:

- code
- commands
- image
- link
- list
- post
- posts_with_tag
- quip
- quote
- show
- tags
- types
- version
- whoami

Okay, fair enough. Let’s start simple.

$ oz --at ozmm.org version
version: "1.2"

Nice. Up to date. How about…

$ oz --at ozmm.org tags
- ruby: 158
- rails: 62
- photos: 53
- games: 46
- svrc: 43
- php: 37
- mac: 34
- quotes: 33
- sanfrancisco: 28
- music: 17
- javascript: 14
- tumblelog: 5
- cocoa: 4
- rss: 4
- subversion: 4
- io: 3
- mysql: 3
- vim: 3

Whoa! Okay, Mr. Web2.0. Let’s see what you have to say about vim…

$ oz --at ozmm.org posts_with_tag vim
- 585: 
  user: admin
  title: ""
  tags: vim
  id: 585
  content: okay we've got ''pastie for vim'':http://pastie.caboo.se/606 ...
  post_type: quip
  user_id: 1
  created_at: 2006-07-10 13:15:00 -07:00
[ ...more posts... ]

We can, of course, also run commands like posts or show 13 to get information on specific posts. What’s this code command, though? I’ll try it.

$ oz --at ozmm.org code
error: You need to login to do that

Ah, so it’s something secretive. If only we were let into the club…

Posting To Your Tumblelog With oz

oz is great for querying tumblelogs, but the real magic is its ability to post to your tumblelog.

Loggin’ In

The first thing we need to do is login. Since ozimodo 1.2 uses cookies for authentication, this is cake. We’ll be doing all of this on our local build of ozimodo, running at localhost:3000.

My username is monet and my password is goodart. Here is how I login:

$ oz --site monet:goodartlocalhost:3000
=> Login successful, you don't have to use --site anymore.
=> No URL to hit.

Ah, great! But what did that do? Well, it created a ~/.ozcache file and stored some information in it.

$ cat ~/.ozcache
cookie: ozimodo=1%26admin%269ce07a6fe388c0ceac0bd5b041757f1b
port: 3000
host: localhost

This file contains the host and port of the tumblelog we want to work on as well as our login cookie, which will keep us from sending our password on every request.

If you don’t want the cache file to be ~/.ozcache you can set the OZCACHE environment variable and oz will use that instead.

Posting

Posting is the easiest part. Since “you know”:configure.html a tumblelog consists of multiple post types, let’s see what post types we have available.

$ oz types
- code: content
- quip: content
- post: content
- quote: 
  - author
  - quote
- link: content
- image: 
  - src
  - alt
  - blurb

We’re given a simple list (somewhat YAML-like) which lists each of our available post types and the fields they accept. code consists of simple content while quote consists of author and quote, right?

Let’s post a quip, which Webster defines as a “clever, witty remark often prompted by the occasion.”

$ oz quip --content 'This command line stuff is so 1970.'
success: Post saved with id of 22

Wow, it really worked. If we were to open up our tumblelog at localhost:3000 we’d see a new quip with our content.

How about posting an image?

$ oz image --src http://facebook.railsconf.org/portraits/139/snap.png \ 
  --tags 'rails dhh' --alt 'dhh is hot'
success: Post saved with id of 23

Even though –tags isn’t listed in the types info, it’s of course a valid switch. You can also use the –title switch with any post.

Personally, I post a lot of links. It would suck to have to format them in textile from the command line each time. Lots of terminating slashes.

$ oz link --url http://www.pjhyett.com/ --text 'PJ is a hack.' --tags link
success: Post saved with id of 24

The link post type is special; our above input will be roughly translated to:

''PJ is a hack.'':http://www.pjhyett.com" before posting.

It’s a nice shortcut.

Tips and Tricks

You can use oz –help for a refresher course at any time. That’ll tell you some helpful information, like that you can use –debug or –clear-cache when you’re really getting into it.

If your login has expired you can simply rock the –login switch without having to re-enter your host and port, ala:

$ oz --login monet:goodart
=> Login successful, you don't have to use --site anymore.

You can mostly ignore the No URL to hit messages as they’re just letting you know that while you may have asked something of oz, it’s not going to request anything of the remote server.

If you’re interested in how the oz API works, writing your own tumbler, or implementing an API which oz can interact with (%(aside)it’s quite versatile%), check out our “API”:api.html docs.

It Broke!

As always, check the “install”:install.html page for the best ways to report a bug. We thank ya.