Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

Install the Heroku CLI and Log In

Create a Heroku account, install the Heroku CLI on Windows, macOS or Linux, log in safely, and learn how the CLI decides which app a command targets.

You can do most things on Heroku from the web dashboard, but day-to-day work happens in the Heroku CLI, a command-line program named heroku. It creates apps, sets config, tails logs, scales dynos and wires your Git repository to the platform. Learning it early pays off in every later lesson.

This lesson covers creating the account, installing the CLI, logging in, and the one concept that confuses beginners most: how a command knows which app you mean.

Before you start

You need:

  • A Heroku account at heroku.com. Accounts require a verified email address and multi-factor authentication, and deploying paid plans requires a payment method. Account rules change over time, so follow the sign-up screens rather than a fixed recipe.
  • Git, because the classic deploy is a git push. Check with git --version.
  • A terminal. Everything below works in PowerShell, Terminal, bash or zsh.

Installing the CLI

The official installers change occasionally; the Heroku Dev Center always has the current list. The usual routes are:

CONSOLE
# macOS (Homebrew)
$ brew tap heroku/brew && brew install heroku

# Ubuntu/Debian and other Linux (official install script)
$ curl https://cli-assets.heroku.com/install.sh | sh

# Any system that already has Node.js
$ npm install -g heroku

On Windows you download the 64-bit installer from the Dev Center and run it, then reopen your terminal so the new PATH is picked up. Whichever way you install, confirm it worked:

CONSOLE
$ heroku --version

The command prints the CLI version, your operating system and the Node.js version it bundles. The CLI checks for updates by itself, and heroku update forces an update.

Tip: if you read an install script before running it, you stay in control of what changes on your machine. curl ... | sh is convenient, but downloading the script first and opening it costs ten seconds.

Logging in

CONSOLE
$ heroku login

The CLI says it is waiting for a key press, then opens your browser so you can sign in to the dashboard, including your second factor. When the browser confirms, the terminal is logged in. Two useful variants:

  • heroku login -i asks for credentials in the terminal. For accounts with multi-factor authentication you must supply an API token as the password.
  • heroku auth:whoami prints the email of the logged-in account.

The CLI stores its credentials in a .netrc file in your home folder (_netrc on Windows). Treat that file like a password. Never commit it, and never paste its contents into chat or issues.

Tokens for scripts and CI

Automation should not use your personal login. Instead:

  • heroku auth:token prints the token the CLI is using, which is a quick way to grab one.
  • heroku authorizations:create --description "ci" creates a separate, revocable OAuth token you can hand to a CI system.
  • Set the token in an environment variable named HEROKU_API_KEY, and the CLI uses it instead of .netrc.

A token can do whatever your account can do, so store it in your CI system's secret store and revoke it if it ever leaks (heroku authorizations:revoke ID).

How a command finds its app

Most commands act on one app. You can state it explicitly with -a (long form --app):

CONSOLE
$ heroku logs --tail -a demo-shop
$ heroku config -a demo-shop

If you leave -a out, the CLI looks for the answer in a fixed order. In practice:

  1. the --app flag, or --remote (-r) which names a Git remote such as staging,
  2. the HEROKU_APP environment variable,
  3. the Git remotes of the repository you are standing in: a remote whose URL looks like https://git.heroku.com/NAME.git tells the CLI the app is NAME.

When it cannot decide, the CLI stops with a message that no app was specified. When you manage several apps (staging and production), name them explicitly or use remotes.

CONSOLE
$ git remote -v
heroku   https://git.heroku.com/demo-shop.git (fetch)
heroku   https://git.heroku.com/demo-shop.git (push)
staging  https://git.heroku.com/demo-shop-staging.git (fetch)
staging  https://git.heroku.com/demo-shop-staging.git (push)

Here heroku logs targets demo-shop (the remote named heroku), while heroku logs -r staging targets demo-shop-staging. The remote is created for you by heroku create or added to an existing repository with heroku git:remote -a demo-shop.

Stand-in: parse remotes and resolve the app

The program below models the lookup order using the same text git remote -v prints. It is not the CLI's code; it shows the logic so you can predict what the real command will do.

Python Stand-in: which app will the CLI pick?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that origin is ignored because its URL is on GitHub, not on git.heroku.com.

Stand-in: spotting a leaked token

Because tokens are so powerful, many teams scan their repositories for them. A real scanner is far more thorough; this toy only checks for obvious assignments, and it uses a fake placeholder value.

Python Stand-in: a toy secret scanner

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

app.py passes because it reads the token from the environment, which is the correct habit, and settings.py is flagged because the value is written into the code.

Common problems

  • heroku: command not found. The install folder is not on PATH. Reopen the terminal, or on Windows sign out and back in.
  • Login opens no browser. Use heroku login -i, or press the key shown in the terminal and copy the URL by hand.
  • Commands act on the wrong app. Run git remote -v and add -a or -r explicitly until the habit is automatic.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command logs you in to Heroku through your browser?

    heroku login opens the browser for sign-in; heroku auth:whoami then confirms the account.
  2. 2. How should a CI system authenticate to Heroku?

    A separate, revocable token kept in the CI secret store limits the damage if it leaks.
  3. 3. You run heroku logs with no -a flag inside a repository whose remote 'heroku' points to https://git.heroku.com/demo-shop.git. Which app is used?

    The CLI reads the Git remote with a git.heroku.com URL and uses the app name from it.
  4. 4. Which flag selects a Git remote such as staging instead of an app name?

    -r (--remote) names a Git remote; -a (--app) names the app itself.

Summary

  • Install the heroku CLI with Homebrew, the install script, npm or the Windows installer, then check it with heroku --version.
  • heroku login signs in through the browser; credentials live in .netrc, which you must protect.
  • Automation uses separate tokens in HEROKU_API_KEY, never your personal login.
  • A command's app comes from -a, then -r, then HEROKU_APP, then a Git remote with a git.heroku.com URL.

Next: Deploy your first app