Heroku CLI

Last updated 29 November 2017

The Heroku Command Line Interface (CLI), formerly known as the Heroku Toolbelt, is a tool for creating and managing Heroku apps from the command line / shell of various operating systems.

It is built with node.js and the code is open sourced. It does not require node.js or other dependencies to run. In all but the ubuntu/debian and npm install methods it will contain its own node.js binary that will not conflict or be available to other applications. It will automatically update itself, the internal version of node, and any installed CLI plugins.

Download and install

MacOS

Homebrew

To install the Heroku CLI with homebrew:

$ brew install heroku/brew/heroku

Compatible with 10.7+

MacOS Installer

Download and run the MacOS installer.

Compatible with 10.7+

Windows

Download and run the Windows installer 32-bit 64-bit.

Ubuntu Snap

This is the recommended method on Ubuntu. Simply run:

$ sudo snap install heroku

Snap is available on other Linux OS’s as well.

Debian/Ubuntu

This version does not autoupdate. You’ll have to manually update the cli with apt-get. Use the standalone install for an autoupdating version of the CLI.

Run the following to add our apt repository and install the CLI:

$ wget -qO- https://cli-assets.heroku.com/install-ubuntu.sh | sh

The script is easily typed in manually if you prefer not to pipe commands to sh.

Standalone

The standalone install is a simple tarball with a binary that is useful in scripted environments or where there is restricted access (non-sudo). These are sample instructions that can be modified to fit your environment. It contains its own node.js binary and will autoupdate like the above install methods.

Download the tarball and extract it so that you can access the binary from your PATH. For example:

# replace REPLACE_ME_OS/REPLACE_ME_ARCH with values as noted below
$ wget https://cli-assets.heroku.com/heroku-cli/channels/stable/heroku-cli-REPLACEME_OS-REPLACE_ME_ARCH.tar.gz -O heroku.tar.gz
$ tar -xvzf heroku.tar.gz
$ mkdir -p /usr/local/lib /usr/local/bin
$ mv heroku-cli-v6.x.x-darwin-64 /usr/local/lib/heroku
$ ln -s /usr/local/lib/heroku/bin/heroku /usr/local/bin/heroku

npm

The CLI is built with node.js and is installable via npm. This is a manual install method that can be used in environments where autoupdating is not ideal or where we do not offer a prebuilt node.js binary.

This installation method is required for users on ARM, BSD, and Arch Linux. You must have node and npm installed already.

$ npm install -g heroku-cli

Verify your installation

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

$ heroku --version
heroku-cli/6.0.0-010a227 (darwin-x64) node-v8.0.0

You should see heroku-cli/x.y.z in the output. If you don’t, but have installed the Heroku CLI, it’s possible you have an old heroku gem on your system - uninstall the gem.

Getting started

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 CLI so that you can use git to push or clone Heroku app repositories:

$ heroku login
Enter your Heroku credentials.
Email: adam@example.com
Password (typing will be hidden):
Authentication successful.

You’re now ready to create your first Heroku app:

$ cd ~/myapp
$ heroku create
Creating app... done, ⬢ sleepy-meadow-81798
https://sleepy-meadow-81798.herokuapp.com/ | https://git.heroku.com/sleepy-meadow-81798.git

Check out our Getting Started for a comprehensive introduction to deploying your first app.

Staying up to date

The Heroku CLI will automatically keep itself and its plugins (except linked plugins) up to date unless you’re using the npm install method or debian/ubuntu package.

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 ~/.local/share/heroku/client. This background check will happen at most once every 4 hours.

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

Troubleshooting

If you’re having trouble using the CLI, here are some helpful environment variables that can be set:

If you’re having issues you can also read the error logfile stored at the following locations:

If you’re having issues, first ensure you’re on the latest version of the CLI. If you’re not, try updating with heroku update.

If updating does not update the CLI, try uninstalling with the uninstall instructions below. Ensure you don’t have Toolbelt installed or the old Heroku gem. Use which heroku or where heroku (on Windows) to find what heroku points to. You may need to modify your PATH to include /usr/local/bin/heroku (for most installations).

If you continue to have problems and the CLI is up to date, or if updating fails for other reasons, you can reset the CLI by deleting its user directories. They will all be replaced automatically and you will not be logged out, but you will lose any installed plugins.

First, run heroku plugins to list out any installed plugins so you can reinstall them.

Then delete the following directories:

Windows:

• %LOCALAPPDATA%\heroku

MacOS/Linux/Other:

• ~/.local/share/heroku (or XDG_DATA_HOME if set)
• Either ~/Library/Caches/heroku on MacOS, or ~/.cache/heroku on Linux/Other (or XDG_CACHE_HOME if set)
• ~/.config/heroku(or XDG_CONFIG_HOME if set)

Login issues

If you are experiencing issues with logging in, try moving your .netrc file. This is where the CLI stores credentials:

$ mv ~/.netrc ~/.netrc.backup
$ heroku login

On Windows the file is named _netrc.

Uninstalling the Heroku CLI

Note that these will also delete all plugins.

MacOS

On MacOS, you can uninstall the CLI by typing:

$ rm -rf /usr/local/heroku
$ rm -rf ~/.local/share/heroku ~/.config/heroku ~/Library/Caches/heroku

Homebrew

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

$ brew uninstall heroku
$ rm -rf ~/.local/share/heroku ~/.config/heroku ~/Library/Caches/heroku

Linux

Standalone installs

For standalone installs, you can uninstall the CLI by typing:

$ rm /usr/local/bin/heroku
$ rm -rf /usr/local/lib/heroku /usr/local/heroku
$ rm -rf ~/.local/share/heroku ~/.config/heroku ~/.cache/heroku ~/.heroku

Debian and Ubuntu installs

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

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

If you have $XDG_DATA_HOME, $XDG_CONFIG_HOME and/or $XDG_CACHE_HOME it will use those variables instead of ~/.local/share, ~/.config/, and ~/.cache, respectively.

You can remove the release key by running these commands:

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

Windows

On Windows, to uninstall the Heroku CLI:

1. Click Start > Control Panel > Programs > Programs and Features.
2. Select Heroku CLI, and then click Uninstall. (Note that the uninstaller is unsigned)

You should also delete the .config/heroku directory inside your home directory.

If this is unsuccessful, manually delete %LOCALAPPDATA%\heroku along with the directory in Program Files.

Uninstalling the legacy heroku gem

To find out where the executable is located, run which.

$ which heroku
/usr/local/heroku/bin/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

Legacy Ruby CLI

If for any reason the new CLI does not work right, or you need to use legacy Ruby-based plugins, use one of these installers:

• MacOS
• Windows
• Standalone: wget -qO- https://toolbelt.heroku.com/install.sh | sh