README

= Heroku API - deploy apps to Heroku from the command line

This library wraps the Heroku REST API for managing and deploying Rails apps to
Heroku.  It can be called as a Ruby library, or invoked from the command line.
Code push and pull is done through Git.

For more information about Heroku, see: http://heroku.com

== Setup

  gem install heroku

If you wish to push or pull code, you must also have a working install of Git
("apt-get install git-core" on Ubuntu or "port install git-core" on OS X), and
an ssh public key ("ssh-keygen -t rsa").

The first time you run a command, such as "heroku list," you will be prompted
for your Heroku username and password.  These are saved to ~/heroku/credentials
for future requests.  Your public key (~/.ssh/id_rsa.pub) will be uploaded to
Heroku after you enter your credentials.

If your public key is in a non-standard location, you can specify the path to your public key using the -k or --key switch ("heroku upload_authkey -k "C:\Documents & Settings\me\mykeys\id_rsa.pub")

== Usage

  heroku list

Get a plain-text listing of apps, the same list that appears on the "My Apps"
page in the web interface.

  heroku create [<appname>]

Create a new app.  If you provide an argument, it will be used to name the app.
(e.g. "heroku create myapp" will produce myapp.heroku.com)  If you
leave off an argument, the app will be assigned an untitled name.

  heroku clone <appname>

Clone the repository of the Heroku app for local work.  Note that this fetches
only code that has been committed to the repo; if you have uncommitted changes
inside the web code editor, these will not be pulled.  This also sets up a few
items for local development, such as writing a database.yml with a sqlite3
adapater.

  git push

Deploy local changes back to Heroku.  You must commit to your local repository
first (e.g., git commit -a).  Note that this will reset the working tree in the
web code editor to match the latest revision pushed, so any uncommitted changes
in Heroku will be overwritten.

  git pull

Pull commits from the Heroku repository into the local repository and update
local working tree.

  heroku destroy <appname>

Permenantly destroy the app named.

  heroku upload_authkey

Upload your ssh public key to Heroku.  This is done automatically when you enter 
your credentials, but if you change your key, you will need to run this
manually. If your public key is in a non-standard location, you can specify 
the key path using the optional -k or --key switch ("heroku upload_authkey -k "C:\Documents & Settings\me\mykeys\id_rsa.pub"). Note that only one key can be active at a time.

== Example Workflow

To start a new app from scratch, work on it locally, and then deploy the changes, use the folowing sequence:

  heroku create myapp
  heroku clone myapp
  cd myapp
  ruby script/server
  [..work locally for a while..]
  git add .
  git commit -m "some changes made locally"
  git push

== Further Reading

The command line internals are implemented by Heroku::CommandLine, look there
if you'd like to know what's going on behind the scenes.

The Heroku::Client class wraps the REST API.  You can use this library if you
wish to access the API from within a Ruby program, such as Capistrano.

Finally, there is documentation for the underlying REST resources:
link:files/REST.html

== Meta

Written by Adam Wiggins (adam at heroku dot com)

Major modifications by Pedro Belo (pedro at heroku dot com)

Patches contributed by: Chris O'Sullivan, Blake Mizerany

Released under the MIT license: http://www.opensource.org/licenses/mit-license.php

Send feedback and questions to the Heroku mailing list: http://groups.google.com/group/heroku

http://github.com/adamwiggins/heroku-client/tree/master