Heroku CLI

11.3.0 verified Sat Apr 25 auth: no javascript

v11.3.0 — official command-line interface for managing Heroku applications and services. Built with oclif and Node.js, it supports app deployment, scaling, monitoring, Postgres databases, CI/CD pipelines, add-ons, SSL certificates, domains, team collaboration, Private Spaces, logs, and a plugin ecosystem. v11 is a major rewrite: ESM-only (converted from CJS), oclif v4, single package (monorepo removed), new color system (ansis replaces chalk), Node >=20 required. Ships TypeScript types. Active development with frequent releases.

Common errors

error Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: /path/to/heroku/node_modules/heroku/lib/index.js ↓

cause Using require() on an ESM-only module in v11.

fix

Change to import heroku from 'heroku'; or use dynamic import.

error Cannot find module '@heroku-cli/plugin-*' ↓

cause v11 removed monorepo. All plugins are now in the main 'heroku' package.

fix

Uninstall @heroku-cli/plugin-* and use 'heroku' directly.

error The engine "node" is incompatible with this module. Expected version ">=20". Got "18.x" ↓

cause Node.js version too old for v11.

fix

Upgrade Node.js to version 20+.

error Error: Command not found. Perhaps you need to install the plugin? ↓

cause Trying to run a plugin command that is not available because oclif v4 changed plugin loading.

fix

Update plugin to oclif v4 compatible version or re-install.

Warnings

breaking v11 converts entire codebase to ESM. require() no longer works. Use import or dynamic import(). ↓

fix Replace require('heroku') with import heroku from 'heroku'. If dynamic import needed, use import('heroku').

breaking v11 removes monorepo structure. All packages consolidated into single npm package 'heroku'. No sub-packages like @heroku-cli/plugin-* are separate. ↓

fix Install only 'heroku' package. Remove separate @heroku-cli/* dependencies.

breaking v11 upgrades to oclif v4. Plugin API changes: command lifecycle, hooks, and config are different. ↓

fix Update plugins to use oclif v4 API. See oclif migration guide.

breaking v11 replaces chalk with ansis for color output. Custom color themes may break. ↓

fix Replace chalk imports with ansis. See ansis documentation for API changes.

breaking v11 drops Node.js <20 support. Minimum engine is 'node': '>=20'. ↓

fix Upgrade Node.js to version 20+.

deprecated redis:maintenance and pg:maintenance commands are deprecated in v10.17.0. ↓

fix Use alternative commands: heroku data:maintenance for Postgres, or remove usage.

gotcha Global install may conflict with npx usage. Use npx heroku for per-version usage. ↓

fix Use npx heroku to avoid version conflicts, or install globally with npm install -g heroku.

Install

npm install heroku

yarn add heroku

pnpm add heroku

Imports

heroku
```
import heroku from 'heroku'
```
Default import works for ESM. CLI is primarily used via command line, not programmatic imports.
Heroku
wrong
```
const Heroku = require('heroku')
```
correct
```
import { Heroku } from 'heroku'
```
ESM-only since v11; require() will throw ERR_REQUIRE_ESM.
Command
```
import { Command } from 'heroku'
```
Class for building CLI plugins. Requires oclif v4 compatibility.

Quickstart

Shows how to create a custom CLI command plugin using the Heroku CLI v11 ESM API.

// Install globally: npm install -g heroku
// Or use without install: npx heroku

import { Command } from 'heroku';

class MyCommand extends Command {
  static description = 'my custom command';
  static flags = {};

  async run() {
    const {args, flags} = await this.parse(MyCommand);
    this.log('Hello from custom command!');
  }
}

export default MyCommand;

// Run: heroku my-command