h1. oz is a command line tumbler.

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.)

h1. 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":http://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...    

h1. 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 @http://localhost:3000@.

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

  $ oz --site monet:goodart@localhost: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 (somewhat YAML-like) list 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 
@http://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.

h1. 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. 

h1. It Broke!

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