dblock/heroku-commander

![](assets/heroku-commander.png)
Heroku::Commander
=================

[![Gem Version](http://img.shields.io/gem/v/heroku-commander.svg)](http://badge.fury.io/rb/heroku-commander)
[![Build Status](http://img.shields.io/travis/dblock/heroku-commander.svg)](https://travis-ci.org/dblock/heroku-commander)
[![Dependency Status](https://gemnasium.com/dblock/heroku-commander.svg)](https://gemnasium.com/dblock/heroku-commander)
[![Code Climate](https://codeclimate.com/github/dblock/heroku-commander.svg)](https://codeclimate.com/github/dblock/heroku-commander)


Master the Heroku CLI from Ruby.

Usage
-----

Add `heroku` and `heroku-commander` to Gemfile.

``` ruby
gem "heroku"
gem "heroku-commander"
```

Heroku Configuration
--------------------

Returns a hash of an application's configuration (output from `heroku config`).


``` ruby
commander = Heroku::Commander.new({ :app => "heroku-commander" })
commander.config # => a hash of all settings for the heroku-commander app
```

Heroku Processes
----------------

Returns or yields an array of processes by running `heroku ps`.

``` ruby
commander = Heroku::Commander.new({ :app => "heroku-commander" })
commander.processes do |process|
  # try process.pid and process.status
end
```

Heroku Run
----------

Executes a command via `heroku run`, pipes and returns output lines. Unlike the heroku client, this also checks the process return code and raises a `Heroku::Commander::Errors::CommandError` if the latter is not zero, which makes this suitable for Rake tasks.

``` ruby
commander = Heroku::Commander.new({ :app => "heroku-commander" })
commander.run "uname -a" # => [ "Linux 2.6.32-348-ec2 #54-Ubuntu SMP x86_64 GNU" ]
```

You can specify the dyno size with `size`.

``` ruby
commander.run "uname -a", { size: "2X" }
```

Heroku Detached Run
-------------------

Executes a command via `heroku run:detached`, spawns a `heroku logs --tail -p pid` for the process started on Heroku, pipes and returns output lines. This also checks the process return code and raises a `Heroku::Commander::Errors::CommandError` if the latter is not zero.

``` ruby
commander = Heroku::Commander.new({ :app => "heroku-commander" })
commander.run("uname -a", { :detached => true }) # => [ "Linux 2.6.32-348-ec2 #54-Ubuntu SMP x86_64 GNU" ]
```

You can examine the output from `heroku logs --tail -p pid` line-by-line.

``` ruby
commander.run("ls -R", { :detached => true }) do |line|
  # each line from the output of the command
end
```

You can pass the following options along with `:detached`:

* **size**: dyno size, eg. `2X` for double-dynos.
* **tail_timeout**: number of seconds to wait before terminating `heroku logs --tail`, expecting more output (defaults to 5).
* **tail_retries**: number of times to restart the tail process on error (defaults to 3).

For more information about Heroku one-off dynos see [this documentation](https://devcenter.heroku.com/articles/one-off-dynos).

More Examples
-------------

See [examples](examples) for more.

Contributing
------------

Fork the project. Make your feature addition or bug fix with tests. Send a pull request. Bonus points for topic branches.

Copyright and License
---------------------

MIT License, see [LICENSE](LICENSE.md) for details.

(c) 2013 [Daniel Doubrovkine](http://github.com/dblock), [Frank Macreery](http://github.com/macreery), [Artsy Inc.](http://artsy.net)