The Heroku CLI

Last updated October 10, 2023

The Heroku Command Line Interface (CLI) is an essential part of using Heroku. With it, you can create and manage Heroku apps directly from the terminal.

Install the Heroku CLI

Prerequisites

The Heroku CLI requires Git, the popular version control system. If you don’t have Git installed, complete:

Install with an Installer

The Windows installers display a warning to some users. To run the installation when this warning shows, “Windows protected your PC,” click More info, verify the publisher as salesforce.com, inc, and then click the Run anyway button.

Snap installs are no longer supported. Use one of these install methods.

macOS

Install Homebrew and run:

$ brew tap heroku/brew && brew install heroku

Windows

Download the appropriate installer for your Windows installation:

64-bit installer

32-bit installer

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/lib/heroku and /usr/local/bin/heroku, run this 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 these tarballs and extract it yourself.

Tarballs

These tarballs are available in gz or xz compression. 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 auto-updating 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 node and npm installed already. This method is also useful if you want fine-grained control over CLI updates, such as in a tested script.

We strongly recommend using one of the other installation methods if possible.

The npm installation method doesn’t auto-update. 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.

The other installation methods include the proper version of Node.js and don’t conflict with any other versions on your system.

Also, npm doesn’t use the yarn lockfile for dependencies like the others, even if you install with yarn. If the CLI’s dependencies become incompatible in minor or patch releases, npm can cause issues.

$ 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 you 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.

$ 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 me@example.com

If you 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: me@example.com
Password: ***************
Two-factor code: ********
Logged in as me@heroku.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. For a full list of commands, see Heroku CLI 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 npm install.

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.

Before using the originally installed client, the heroku binary checks for an up-to-date client in ~/.local/share/heroku/client.

Latest Release SHAs

Darwin

Linux

Windows

Useful CLI Plugins

Install a CLI plugin with heroku plugins:install someplugin, and you can extend your CLI installation. For more information on plugin management, see Using CLI Plugins.

Here are some useful plugins.

CLI Architecture

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 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 heroku update.

  • 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 npm or yarn, you must use npm upgrade -g heroku or yarn global upgrade heroku.

If the CLI fails to update, uninstall it, and then reinstall 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 still encounter an issue, you can set these debugging environment variables to help diagnose the issue.

Environment Variable Description
HEROKU_DEBUG=1 Shows debugging information mostly related to Heroku API interactions
HEROKU_DEBUG_HEADERS=1 Alongside HEROKU_DEBUG=1, shows HTTP headers
DEBUG=* Shows verbose debugging information

You can also check the CLI’s error logfile, stored at one of these locations, depending on your operating system.

OS Location
macOS ~/Library/Caches/heroku/error.log
Windows %LOCALAPPDATA%\heroku\error.log
Linux/Other ~/.cache/heroku/error.log (or XDG_CACHE_HOME if set)

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.

First, run heroku plugins to list your installed plugins so that you can make sure to reinstall them.

Then, delete these 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)

Login Issues

If you have issues logging in, move your .netrc file. This file is where the CLI stores credentials.

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

On Windows, the file is named _netrc.

Homebrew-Specific Issues

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.

To see what binary heroku points to, run which heroku. If it doesn’t point to /usr/local/bin/heroku, delete the binary it points to. You can also make /usr/local/bin/ higher up in your PATH environment variable by modifying your ~/.bashrc file or equivalent.

Next, run brew link --overwrite heroku to make sure that /usr/local/bin/heroku points to the new CLI. If you continue to have trouble, run brew doctor to identify any issues with your system.

Apple Silicon Issues

If you get this 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.

macOS

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

Homebrew Installs

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

Linux

Standalone Install

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_DATA_HOME, or $XDG_CACHE_HOME, it uses those variables instead of ~/.local/share, and ~/.cache.

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. From the Start menu, click Control Panel, Programs, and then Program and Features..
  2. Select Heroku CLI, and then click Uninstall. 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.

$ which heroku
/usr/local/heroku/bin/heroku

Ensure that the path to the heroku command isn’t in a Ruby gem directory.

If it is, uninstall it and any other heroku gems.

$ gem uninstall heroku --all

Feedback

Log in to submit feedback.