The Heroku CLI
Last updated 01 September 2020
Table of Contents
The Heroku Command Line Interface (CLI) makes it easy to create and manage your Heroku apps directly from the terminal. It’s an essential part of using Heroku.
Download and install
The Heroku CLI requires Git, the popular version control system. If you don’t already have Git installed, complete the following before installing the CLI:
Currently, the Windows installers may display a warning titled “Windows protected your PC”. To run the installation when this warning is shown, click “More info”, verify the publisher as “Heroku, Inc.”, then click the “Run anyway” button.
Other installation methods
The standalone install is a simple tarball with a binary. It contains its own node.js binary and will autoupdate like the above install methods.
To quickly setup into
/usr/local/bin/heroku, run this script (script requires sudo and not Windows compatible):
$ curl https://cli-assets.heroku.com/install.sh | sh
Otherwise, download one of the tarballs below and extract it yourself.
These are available in
xz is much smaller but
gz is more compatible.
Ubuntu / Debian apt-get
$ curl https://cli-assets.heroku.com/install-ubuntu.sh | sh
This package is community maintained and not by Heroku.
$ yay -S heroku-cli
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 Heroku does not offer a prebuilt Node.js binary.
It’s strongly recommended to use one of the other installation methods if possible.
This installation method does not autoupdate and requires you to use your system’s version of Node.js, which may be older than the version Heroku develops the CLI against. Heroku uses very current releases of Node.js and does not back-support older versions.
If you use any of the other installation methods the proper version of Node.js is already included, and it doesn’t conflict with any other version on your system.
Also, this method won’t use the yarn lockfile for dependencies like the others do (even if you install with yarn). This may cause issues if the CLI’s dependencies become incompatible in minor or patch releases.
This method is useful if you want fine-grained control over CLI updates such as in a tested script.
This installation method is required for users on ARM and BSD. You must have
npm installed already.
$ npm install -g heroku
Verifying your installation
To verify your CLI installation, use the
heroku --version command:
$ heroku --version heroku/7.0.0 (darwin-x64) node-v8.0.0
You should see
heroku/x.y.z in the output. If you don’t, but you have installed the Heroku CLI, it’s possible you have an old
heroku gem on your system. Uninstall it with these instructions.
After you install the CLI, run the
heroku login command. You’ll be prompted to enter any key to go to your web browser to complete login. The CLI will then log you in automatically.
$ heroku login heroku: Press any key to open up the browser to login or q to exit › Warning: If browser does not open, visit › https://cli-auth.heroku.com/auth/browser/*** heroku: Waiting for login... Logging in... done Logged in as firstname.lastname@example.org
If you’d prefer to stay in the CLI to enter your credentials, you may run
heroku login -i
$ heroku login -i heroku: Enter your login credentials Email: email@example.com Password: *************** Two-factor code: ******** Logged in as firstname.lastname@example.org
The CLI saves your email address and an API token to
~/.netrc for future use. For more information, see Heroku CLI Authentication.
Now you’re 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 your preferred language’s getting started guide for a comprehensive introduction to deploying your first app.
Staying up to date
The Heroku CLI keeps itself and its plugins (except linked plugins) up to date automatically, unless you installed the Debian/Ubuntu package or used
When you run a
heroku command, a background process checks for the latest available version of the CLI. If a new version is found, it’s downloaded and stored in
~/.local/share/heroku/client. This background check happens at most once every 4 hours.
heroku binary checks for an up-to-date client in
~/.local/share/heroku/client before using the originally installed client.
Latest release SHAs
Useful CLI plugins
CLI plugins allow you to extend your CLI installation. Install a CLI plugin with
heroku plugins:install someplugin. See Using CLI Plugins for more information on plugin management.
Here are some useful plugins you might want to try:
- heroku-builds — create builds from tarballs
- heroku-repo — purge build cache, reset repo, and other commands to manipulate the Heroku git repository
api — make ad-hoc API requests (such as
heroku api GET /account)
heroku-pg-extras — Add extra
- heroku-slugs — Downloads app slugs
- heroku-kafka — Manage Heroku Kafka
- heroku-papertrail — Display, tail, and search for logs with Papertrail
The Heroku CLI is built with the Open CLI Framework (oclif), developed within Heroku / Salesforce. oclif is available as a framework for any developer to build a large or a small CLI. The framework includes a CLI generator, automated documentation creation, and testing infrastructure.
The code for the Heroku CLI is also open source. It does not require Node.js or any other dependencies to run. Unless you install the Debian/Ubuntu package or use
npm install, the CLI contains its own Node.js binary that does not conflict with other applications.
If you’re having issues with the CLI, first ensure that you’re using the latest version. If you’re not, try updating with
Not all methods of installation support
- If you installed the CLI with
apt, you need to use
sudo apt-get update && sudo apt-get upgrade herokuinstead.
- If you installed the CLI with
yarn, you need to use
npm upgrade -g herokuor
yarn global upgrade herokuinstead.
If the CLI fails to update, try uninstalling it with the instructions below, then reinstalling it. Ensure that you don’t have the legacy Heroku Toolbelt or Heroku Ruby gem installed by using
which heroku or
where heroku (on Windows) to confirm what the
heroku command points to. You might need to modify your
PATH to include
/usr/local/bin/heroku (for most installations).
If you’re still encountering an issue, you can set the following debugging environment variables to help diagnose it:
||Shows debugging information mostly related to Heroku API interactions|
||Shows very verbose debugging information|
You can also check the CLI’s error logfile, which is stored at one of the following locations depending on your operating system:
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. These directories are replaced automatically and you will not be logged out, but you will lose any installed plugins.
heroku plugins to list your installed plugins so you can make sure to reinstall them.
Then, delete the following directories:
~/Library/Caches/herokuon macOS, or
~/.cache/herokuon Linux/Other (or
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
If you get legacy warnings even though you installed the latest homebrew version of heroku, this is happening because the binary
heroku command in your
PATH environment variable is not pointing to the version that brew installed.
which heroku to see what binary
heroku is pointing to. If it is not
/usr/local/bin/heroku, you need to either delete the binary it is pointing to, or make
/usr/local/bin/ higher up in your
PATH environment variable by modifying your
~/.bashrc file or equivalent.
brew link --overwrite heroku to make sure that
/usr/local/bin/heroku is pointing to the new CLI. If you continue to have trouble, run
brew doctor which should point out any issues with your system.
Uninstalling the Heroku CLI
Note that this also deletes all CLI plugins.
On macOS, you can uninstall the CLI by typing:
$ rm -rf /usr/local/heroku /usr/local/lib/heroku /usr/local/bin/heroku ~/.local/share/heroku ~/Library/Caches/heroku
If you installed the Heroku CLI using Homebrew, you can uninstall the CLI by typing:
$ brew uninstall heroku $ rm -rf ~/.local/share/heroku ~/Library/Caches/heroku
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 ~/.cache/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_CACHE_HOME it will use those variables instead of
You can remove the release key by running these commands:
$ sudo apt-key list $ sudo apt-key del KEYFROMABOVE
On Windows, to uninstall the Heroku CLI:
Start > Control Panel > Programs > Programs and Features.
Heroku CLI, and then click
Uninstall. (Note that the uninstaller is unsigned)
The Windows uninstaller is not automatically updated alongside the CLI. If it’s been a while since you first installed the CLI and you’re attempting to uninstall it to fix an issue, you might first need to manually install the latest version of the CLI to obtain an up-to-date uninstaller.
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 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
$ gem uninstall heroku --all