Deep-dive on the Next Gen Platform. Join the Webinar!

Skip Navigation
Show nav
Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
    • .NET
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
Hide categories

Categories

  • Heroku Architecture
    • Compute (Dynos)
      • Dyno Management
      • Dyno Concepts
      • Dyno Behavior
      • Dyno Reference
      • Dyno Troubleshooting
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Developer Tools
    • Command Line
    • Heroku VS Code Extension
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery & Integration (Heroku Flow)
    • Continuous Integration
  • Language Support
    • Node.js
      • Working with Node.js
      • Troubleshooting Node.js Apps
      • Node.js Behavior in Heroku
    • Ruby
      • Rails Support
      • Working with Bundler
      • Working with Ruby
      • Ruby Behavior in Heroku
      • Troubleshooting Ruby Apps
    • Python
      • Working with Python
      • Background Jobs in Python
      • Python Behavior in Heroku
      • Working with Django
    • Java
      • Java Behavior in Heroku
      • Working with Java
      • Working with Maven
      • Working with Spring Boot
      • Troubleshooting Java Apps
    • PHP
      • PHP Behavior in Heroku
      • Working with PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
    • .NET
      • Working with .NET
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
      • Migrating to Heroku Postgres
    • Heroku Key-Value Store
    • Apache Kafka on Heroku
    • Other Data Stores
  • AI
    • Working with AI
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
      • Single Sign-on (SSO)
    • Private Spaces
      • Infrastructure Networking
    • Compliance
  • Heroku Enterprise
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Extending Heroku
  • Building CLI Plugins
  • Developing CLI Plugins

Developing CLI Plugins

English — 日本語に切り替える

Last updated January 31, 2025

Table of Contents

  • Creating the plugin
  • Installing the plugin
  • Using the Heroku API
  • Debugging tips
  • Releasing plugins

The Heroku CLI is based on oclif which has plugin functionality. Users install plugins with heroku plugins:install PLUGINNAME, where PLUGINNAME is an npm package on npmjs.com. Plugin developers can also link them into the CLI with heroku plugins:link, as described below.

For more information on the Heroku CLI, check out the project on GitHub.

The plugins will be run with a current version of node (usually the latest) no matter what version of node is installed on the machine (if any). There is no need to support old versions of node.

We will walk you through developing a simple hello world plugin. For a more complete example, check out the heroku-git plugin.

Creating the plugin

Generate a new plugin with oclif: (npx comes included in npm and will automatically install oclif for you)

$ npx oclif generate myplugin

Installing the plugin

While plugins on npmjs.com can be installed with heroku plugins:install, when developing plugins locally you will want to use heroku plugins:link. This will validate the plugin, then link it in ~/.local/share/heroku/plugins/linked.json.

To setup this plugin locally, go to the root of your plugin directory and link the plugin:

$ cd myplugin
$ heroku plugins:link
$ heroku hello world
hello world! (./src/commands/hello.ts)

Using the Heroku API

oclif commands work just fine inside the CLI, but if we want to use the Heroku API for anything we need to use the Heroku CLI command base class.

First add the base class to the project with yarn add @heroku-cli/command as well as the API schema types with yarn add -D @heroku-cli/schema. Then edit the command like the following:

// note that we are using @heroku-cli/command instead of @oclif/command
// this inherits from @oclif/command but extends it with Heroku-specific functionality
import {Command, flags} from '@heroku-cli/command'
import * as Heroku from '@heroku-cli/schema'

export default class AppCommand extends Command {
  static description = 'say hi to an app'
  static flags = {
    remote: flags.remote(),
    app: flags.app({required: true})
  }

  async run () {
    const {flags} = await this.parse(AppCommand)
    const response = await this.heroku.get<Heroku.App>(`/apps/${flags.app}`)
    const app = response.body
    console.dir(app)
  }
}

For more information on what command options are available, read the oclif documentation.

Debugging tips

Use console.dir() to pretty-print an object.

Run a command with HEROKU_DEBUG=1 to print debugging statements. HEROKU_DEBUG_HEADERS=1 to also get the headers. Use DEBUG=* for lots of internal debug output.

Inspect ~/Library/Caches/heroku/error.log for extra error output.

Releasing plugins

All that is needed to run heroku plugins:install to install a plugin is for it to be published on npmjs.com.

Create an account then log into it from your terminal:

$ npm login
Username: jdxcode
Password:
Email: (this IS public) npm@heroku.com
Logged in as jdxcode on https://registry.npmjs.org/

We recommend using np to make publishing to npm easier. You can release an update with:

$ npx np

It will prompt for a new version, run the tests, as well as other checks to make sure a proper release is being performed.

Release Channels

To have a beta, staging, or development channel for plugins, you can use npm dist-tags.

First publish a package to a dist-tag:

npm publish --tag beta

Then install the plugin with that tag:

heroku plugins:install myplugin@beta

The CLI will continue to update the plugin to any new releases on the beta channel.

Keep reading

  • Building CLI Plugins

Feedback

Log in to submit feedback.

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure
  • .NET

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing
  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Github
  • LinkedIn
  • © 2025 Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners. Salesforce Tower, 415 Mission Street, 3rd Floor, San Francisco, CA 94105, United States
  • heroku.com
  • Legal
  • Terms of Service
  • Privacy Information
  • Responsible Disclosure
  • Trust
  • Contact
  • Cookie Preferences
  • Your Privacy Choices