Heroku CLI
Last updated 01 June 2017
Table of Contents
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
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/Debian and Windows Bash
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:
For Windows Bash you must install the Windows Subsystem for Bash and execute these commands through bash, not cmd.exe or PowerShell.
$ sudo apt-get install software-properties-common # debian only
$ sudo add-apt-repository "deb https://cli-assets.heroku.com/branches/stable/apt ./"
$ curl -L https://cli-assets.heroku.com/apt/release.key | sudo apt-key add -
$ sudo apt-get update
$ sudo apt-get install heroku
Standalone version
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:
Don’t just copy and paste! Some modification is required. (see below)
# replace REPLACE_ME_OS/REPLACE_ME_ARCH with values as noted below
$ wget http://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
Where REPLACE_ME_OS is one of “linux”, “darwin”, “windows” and REPLACE_ME_ARCH is one of “x64” or “x86” You also must replace “6.x.x” with the actual version.
npm version
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.
It’s strongly recommended to use one of the other installation methods if possible This installation method will not autoupdate and requires you to have a compatible version of node. We tend to use very current releases of node and do not back-support older versions.
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.
Technical details
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 ~/.cache/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-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:
- Click Start > Control Panel > Programs > Programs and Features.
- 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.
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: