The Heroku CLI
Last updated May 02, 2023
Table of Contents
The Heroku Command Line Interface (CLI) lets you create and manage Heroku apps directly from the terminal. It’s an essential part of using Heroku.
Install the Heroku CLI
The Heroku CLI requires Git, the popular version control system. If you don’t already have Git installed, complete the following:
Install with an Installer
The Windows installers display a warning titled “Windows protected your PC” to some users. To run the installation when this warning shows, click “More info”, verify the publisher as “salesforce.com, inc”, then click the “Run anyway” button.
Snap installs are no longer supported. Please use another install method below.
Install Homebrew and run:
$ brew tap heroku/brew && brew install heroku
Download the appropriate installer for your Windows installation:
Standalone Installation with a Tarball
The standalone install is a simple tarball with a binary. It contains its own node.js binary and autoupdates.
To set up the CLI in
/usr/local/bin/heroku, run the following script. The script requires sudo and isn’t Windows compatible.
$ curl https://cli-assets.heroku.com/install.sh | sh
You can also download one of the following tarballs and extract it yourself.
These tarballs are available in
xz is much smaller but
gz is more compatible.
Install with Ubuntu / Debian apt-get
$ curl https://cli-assets.heroku.com/install-ubuntu.sh | sh
This version doesn’t autoupdate. Update it manually via
apt-get. Use the standalone installation for an autoupdating version of the CLI.
Install for Arch Linux
Install the community-maintained heroku-cli 7.60.1-1:
$ yay -S heroku-cli
Install with npm
The CLI is built with Node.js and installable via
npm. Use this manual install method in environments where autoupdating isn’t ideal, or where Heroku doesn’t offer a prebuilt Node.js binary. ARM and BSD must use this installation method. You must have
npm installed already. This method is also useful if you want fine-grained control over CLI updates such as in a tested script.
It’s strongly recommended to use one of the other installation methods if possible.
This installation method doesn’t autoupdate. It also requires you to use your system’s version of Node.js, which can be older than the version Heroku develops the CLI against. Heroku uses current releases of Node.js and doesn’t support older versions.
If you use any of the other installation methods, it includes the proper version of Node.js and doesn’t conflict with any other version on your system.
Also, this method doesn’t use the yarn lockfile for dependencies like the others do, even if you install with yarn. This method can cause issues if the CLI’s dependencies become incompatible in minor or patch releases.
$ npm install -g heroku
Verify Your Installation
To verify your CLI installation, use the
heroku --version command:
$ heroku --version heroku/7.0.0 (darwin-x64) node-v8.0.0
The output looks like
heroku/x.y.z. If you don’t see that output, and installed the Heroku CLI, check if you have an old
heroku gem on your system. Uninstall it with these instructions.
Get Started with the Heroku CLI
After you install the CLI, run the
heroku login command. Enter any key to go to your web browser to complete login. The CLI then logs 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 email@example.com
If you’d prefer to stay in the CLI to enter your credentials, run
heroku login -i.
You can’t use the
-i option if you have multi-factor authentication enabled due to a technical dependency on web browsers for verification.
$ heroku login -i heroku: Enter your login credentials Email: firstname.lastname@example.org Password: *************** Two-factor code: ******** Logged in as email@example.com
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. See Heroku CLI Commands for a full list of commands.
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:
- api — Make ad-hoc API requests (such as
heroku api GET /account).
- free - Find all your apps that use free dynos, free Heroku Postgres, or free Heroku Data for Redis plans.
- heroku-builds — View builds, purge the build cache, and create builds from tarballs.
- heroku-repo — Commands to manipulate an app’s Heroku git repository.
- heroku-pg-extras — Provides extra
- heroku-slugs — Downloads app slugs.
- heroku-kafka — Manage Heroku Kafka.
- heroku-guardian - View various configurations within Heroku that help secure your apps, spaces, and users.
- heroku-papertrail — Display, tail, and search for logs with Papertrail.
- advanced-scheduler — Create and manage your Advanced Scheduler triggers.
- heroku-cron — Create, manage and monitor your Cron To Go jobs using interactive command line or using manifest files in post-deploy scripts.
- borealis-pg — Enable advanced interactions with a Borealis Isolated Postgres add-on.
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 used
npm install, the CLI contains its own Node.js binary that doesn’t conflict with other applications.
Troubleshooting the Heroku CLI
Not all methods of installation support
- If you installed the CLI with
apt, you must use
sudo apt-get update && sudo apt-get upgrade heroku.
- If you installed the CLI with
yarn, you must use
npm upgrade -g herokuor
yarn global upgrade heroku.
If the CLI fails to update, try uninstalling it, 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. Some users must modify their
PATH to include it (
/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 verbose debugging information|
You can also check the CLI’s error logfile, 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, reset the CLI by deleting its user directories. These directories get replaced automatically. Deleting them doesn’t log you out but you 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’re experiencing issues with logging in, try moving your
.netrc file. This file is where the CLI stores credentials:
$ mv ~/.netrc ~/.netrc.backup $ heroku login
On Windows, the file is named
If you get legacy warnings even with the latest homebrew version of
heroku installed, the binary
heroku command in your
PATH environment variable isn’t pointing to the version that brew installed.
which heroku to see what binary
heroku is pointing to. If it isn’t
/usr/local/bin/heroku, delete the binary it is pointing to. You can also 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 to point out any issues with your system.
Apple Silicon Issues
If you’re getting the following error on a machine with an Apple M1 chip, you haven’t installed or declined to install Rosetta 2.
Bad CPU type in executable
Installing Rosetta 2 resolves this issue.
If you don’t want to install Rosetta 2 on your machine, you can install the Heroku npm package globally and use your own Node binary locally. Only v16 of Node has M1 ARM support and npm isn’t the recommended install method.
Uninstall the Heroku CLI
This action 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 uses 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, manually install the latest version of the CLI to obtain an up-to-date uninstaller.
If the uninstall is unsuccessful, manually delete
%LOCALAPPDATA%\heroku along with the directory in Program Files.
Uninstall the Legacy heroku Gem
To find out where the executable is, run
$ which heroku /usr/local/heroku/bin/heroku
Ensure the path to the
heroku command isn’t in a Ruby gem directory.
If it is, uninstall it and any other
$ gem uninstall heroku --all