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

This library wraps the REST API for managing and deploying Rails apps to the
Heroku platform.  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

== Sample Workflows

Start a new app from scratch, work on it locally, then deploy the changes:

  heroku create newapp
  git clone git@heroku.com:newapp.git
  cd newapp
  rake db:migrate
  script/server
  [..work locally for a while..]
  git add .
  git commit -m "some changes made locally"
  git push

Deploy an existing Rails app:

  cd ~/projects/existingapp
  # skip the next three commands if the app already has a git repo
  git init
  git add .
  git commit -m "init"
  heroku create existingapp-deploy
  git remote add heroku git@heroku.com:existingapp-deploy.git
  git push -f heroku

== 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_[rd]sa.pub) will be uploaded
to Heroku after you enter your credentials.  Use heroku keys --add if you wish
to upload additional keys or specify a key in a non-standard location.

== Command-Line Usage

  heroku list

Get a list of your apps.

  heroku create [<appname>]

Create a new app.  If you don't provide a name, one will be assigned (you can
change it later with the update --name command).  The web url and git repo url
will be shown as the command's output.

  git clone git@heroku.com:<appname>.git

Clone the repository of the Heroku app for local work.  Note that this fetches
only code that has been committed to the repo; uncommitted changes inside the
web code editor will not be pulled.

  git push

Deploy local changes back to Heroku.  You must commit to your local repository
first (e.g., git commit -a).  Use -f if you are pushing for the first time to
force overwriting the repo.

  heroku info <app>

Show info about the app like the web url, git repo, and sharing settings.

  heroku update <app> [--name <newname>] [--public (true|false)] [--mode (production|development)]

Update settings on the app, providing one or more of the options shown.

  heroku sharing <app> --add <email> --access (edit|view)
  heroku sharing <app> --remove <email>

Manage collaborators on the app.  An invitation will be sent by email for the
new collaborator to view or edit the app.

  heroku rake <app> <command>

Execute a rake command on the Heroku app.

  heroku destroy <app>

Permenantly destroy the app.

  heroku keys
  heroku keys --add [<path to keyfile>]
  heroku keys --remove [keyname]
  heroku keys --remove all

Manage your ssh public keys for git push/pull on your apps.  The default key
(~/.ssh/id_[rd]sa.pub) is uploaded automatically when you enter your
credentials.  If you wish to add additional keys, or you have a key in a
nonstandard location, you can use heroku keys --add.  Without any arguments,
this will list all the keys attached to your Heroku user account.

== Further Reading

The Heroku::Client class wraps the REST API.  You can instantiate this class to
access the API from within a Ruby program, such as a Capistrano script.

Documentation for the underlying REST resources: link:files/REST.html

== Meta

Written by Adam Wiggins

Major modifications by Pedro Belo

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