A command line interface for managing multiple Heroku accounts and apps.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Gem Version Code Climate GPA Code Climate Coverage Gemnasium Status Travis CI Status Patreon

A command line interface for managing multiple Heroku accounts and apps. This gem builds upon capabilities found in the Heroku gem by adding multi-account support so you can switch between accounts using a single command line command. In addition to the multi-account support, this gem also allows native Heroku commands enhanced with your current account settings. Once you get your feet wet with this gem, you'll soon find that you'll be using less of the heroku command and more of the hp command.


This gem is no longer supported and will be permanently be removed on January 1st, 2017.

Table of Contents


  • Multiple account management.
  • Remote database management.
  • Convenient workflow commands within the context of current application.


  1. UNIX-based OS.
  2. MRI 2.x.x.
  3. Heroku account.
  4. Heroku PG Backups Addon.


For a secure install, type the following from the command line (recommended):

gem cert --add <(curl --location --silent https://www.alchemists.io/gem-public.pem)
gem install heroku_plus --trust-policy MediumSecurity

NOTE: A HighSecurity trust policy would be best but MediumSecurity enables signed gem verification while allowing the installation of unsigned dependencies since they are beyond the scope of this gem.

For an insecure install, type the following (not recommended):

gem install heroku_plus

You can change the default settings for this gem by creating the following file:


The contents of the file should look like this (where the default values can be changed to your liking):

:ssh_id: id_rsa
:mode: stage
:skip_switch_warnings: false
:pg_restore_options: -O -w
:current_account: ra

You can create a new account by running the following from the command line:

hp -a -c <account name>


From the command line, type: hp

hp -C, [--console]            # Open remote console.
hp -a, [--account=ACCOUNT]    # Manage accounts.
hp -d, [--database=DATABASE]  # Manage PostgreSQL database.
hp -e, [--edit]               # Edit gem settings in default editor.
hp -h, [--help=HELP]          # Show this message or get help for a command.
hp -m, [--mode=MODE]          # Manage modes.
hp -p, [--pass=PASS]          # Pass command to Heroku.
hp -r, [--restart]            # Restart remote server.
hp -v, [--version]            # Show gem version.

For account options, type: hp help account

-c, [--create=CREATE]      # Create account.
-s, [--switch=SWITCH]      # Switch account.
-d, [--destroy=DESTROY]    # Delete account.
-l, [--list], [--no-list]  # Show configured accounts.
-i, [--info], [--no-info]  # Show current credentials and SSH identity.

For mode options, type: hp help mode

-s, [--switch=SWITCH]      # Switch mode.
-l, [--list], [--no-list]  # Show modes.

For more db options, type: hp help db

-m, [--migrate], [--no-migrate]      # Migrate remote PostgreSQL database and restart server.
-b, [--backup], [--no-backup]        # Backup remote PostgreSQL database.
-d, [--download], [--no-download]    # Download last remote PostgreSQL database backup.
-t, [--transfer=TRANSFER]            # Transfer remote PostgreSQL database backup for current mode to specified mode.
-i, [--import=IMPORT]                # Import last remote PostgreSQL database backup into local database.
-I, [--import-latest=IMPORT_LATEST]  # Import latest (i.e. now) remote PostgreSQL database backup into local database.
-R, [--reset=RESET]                  # Reset and destroy all data in remote PostgreSQL database.


From this point forward, you can switch between accounts as follows:

  1. Change directory to the app you want to work on.
  2. Type: hp -a -s
  3. Make changes to your code.
  4. Type: git commit -a “Your comments.”
  5. Type: git push heroku master.
  6. Have a beer.


The following is an overview of all files used by this gem (including the Heroku gem) to manage your accounts:

~/.netrc - Used by the Heroku gem, holds current account credentials. When account switching, the contents of this
           file will be replaced by the contents of a *.account file.
~/.heroku_plusrc - Settings for this gem (as mentioned above).
~/.heroku/<name>.account - Credentials for a named account (there is one for each account). When account switching,
                           the contents of this file will replace the contents of the .netrc file.
~/.ssh/config - The SSH configuration settings for all accounts.
~/.ssh/<name> - The private SSH identity for an account (there is one for each account). Defaults to id_rsa.
~/.ssh/<name>.pub - The public SSH identity for an account (there is one for each account). Defaults to id_rsa.pub.

Details of each file is described below.

Netrc (~/.netrc)

This file is automatically managed for you and looks like the following:

machine api.heroku.com
  login example@example.com
  password VbcudJUkMniDfRydcs8Byzwhr3BzHPqC
  login example@example.com
  password VbcudJUkMniDfRydcs8Byzwhr3BzHPqC

Heroku+ Settings (~/.heroku_plusrc)

The global settings for Heroku+ (see details mentioned earlier).

Heroku+ Account Credentials (~/.heroku/<name>.account)

Contains account credentials for a specific account. The file data is the same as mentioned above in the .netrc file.

SSH Configuration (~/.ssh/config)

This file is automatically managed for you and looks like the following:

Host heroku.example
 HostName heroku.com
 User example@example.com
 IdentityFile /Users/example/.ssh/example

SSH Identity (~/.ssh/id_rsa and ~/.ssh/id_rsa.pub)

You need private and public SSH identity files for each Heroku account (it is assumed you are using RSA encryption but any encryption technique will work). These files are automatically created for you when running the "hp -a -c" command, but here is how to create them manually:

ssh-keygen -t rsa -C "<email>" -f ~/.ssh/id_rsa

Git Configuration (~/Development/Projects/your_project/.git/config)

This is somewhat outside the scope of documentation for this gem but I think it is important to mention. The Git configuration file, as you might know, is what configures Git for your particular project. If you have more than one branch (i.e. remote) listed within this config file you will still need to pass the --app command when issuing Heroku commands. The reason for supporting multiple branches is because you might wish to have a stage and production server where you deploy to stage before updating your production server. For example, your config file might look like this:

[remote "example-production"]
[remote "example-stage"]

This would then require you use the --app option when issuing a Heroku command. For example:

heroku restart --app example-production
heroku restart --app example-stage

Which can be done faster by switching to the mode you want to run in (i.e. production or stage) and then running the necessary command. Example:

hp -m -s production
hp -r

The above basically says that you want to switch to "production" mode (i.e. git branch) and then execute an app restart via the "hp -r" command.

Finally, while this gem alleviates the need to specify the --app command when dealing within multiple Heroku accounts, it does not help you when dealing with multiple branches within a single Heroku account. That, I leave to you.


To test, run:

bundle exec rake


Read Semantic Versioning for details. Briefly, it means:

  • Patch (x.y.Z) - Incremented for small, backwards compatible bug fixes.
  • Minor (x.Y.z) - Incremented for new, backwards compatible public API enhancements and/or bug fixes.
  • Major (X.y.z) - Incremented for any backwards incompatible public API changes.

Code of Conduct

Please note that this project is released with a CODE OF CONDUCT. By participating in this project you agree to abide by its terms.


Read CONTRIBUTING for details.


Copyright (c) 2010 Alchemists. Read the LICENSE for details.


Read the CHANGELOG for details. Built with Gemsmith.


Developed by Brooke Kuhlmann at Alchemists.