Heroku CLI

Last Updated: 10 March 2015

cli heroku

Table of Contents

The heroku command-line tool is an interface to the Heroku Platform API and includes support for things like creating/renaming apps, running one-off dynos, taking backups, and configuring add-ons. Most app management activities require the Heroku CLI to be installed and configured alongside your local working environment.

Installing the Heroku CLI

Set up your local workstation with the Heroku command-line client, the Git revision control system and the Foreman app runner by installing the Heroku Toolbelt.

To verify your toolbelt installation use the heroku --version command.

$ heroku --version
heroku-toolbelt/2.39.0 (x86_64-darwin10.8.0) ruby/1.9.3

You should see heroku-toolbelt/x.y.z in the output. If you don’t, but have installed the toolbelt, it’s possible you have the old heroku gem on your system. To find out where the executable is located, run which.

$ which heroku

The path to the heroku command should not be a Ruby gem directory. If it is, uninstall it and any other heroku gems:

$ gem uninstall heroku --all

Retry heroku --version until it reflects the expected heroku-toolbelt output.

Logging in

You will be asked to enter your Heroku credentials the first time you run a command; after the first time, your email address and an API token will be saved to ~/.netrc for future use. For more information, see Heroku CLI Authentication

It’s generally a good idea to login and add your public key immediately after installing the heroku toolbelt so that you can use git to push or clone Heroku app repositories:

$ heroku login
Enter your Heroku credentials.
Email: joe@example.com
Uploading ssh public key /Users/joe/.ssh/id_rsa.pub

Autoupdate was added to the Toolbelt in version 2.32.0. If you have an older version, please reinstall the Toolbelt.

Staying up to date

The Heroku Toolbelt will automatically keep itself up to date.

How it works

When you run a heroku command, a background process will be spawned that checks a URL for the latest available version of the CLI. If a new version is found, it will be downloaded and stored in ~/.heroku/client. This background check will happen at most once every 5 minutes.

The heroku binary will check for updated clients in ~/.heroku/client before loading the system-installed version.

Uninstalling the Heroku CLI

Mac OS X

On Mac OS X, you can uninstall the Toolbelt by typing:

$ rm -rf /usr/local/heroku
$ rm -rf ~/.heroku


If you installed the Heroku Toolbelt using Homebrew, you can uninstall the Toolbelt by typing:

$ brew uninstall heroku
$ rm -rf ~/.heroku


Stand-alone Linux installs

For stand-alone Linux installs, you can uninstall the Toolbelt by typing:

$ rm -rf /usr/local/heroku
$ rm -rf ~/.heroku

Debian and Ubuntu installs

For Debian/Ubuntu, you can uninstall the Toolbelt by typing:

$ sudo apt-get remove heroku-toolbelt
$ sudo rm /etc/apt/sources.list.d/heroku.list

You can remove the release key by running these commands:

$ sudo apt-key list
$ sudo apt-key del KEYFROMABOVE


On Windows, to uninstall the Toolbelt:

  1. Click Start > Control Panel > Programs > Programs and Features.
  2. Select Heroku Toolbelt, and then click Uninstall.

You should also delete the _heroku directory inside your home directory.