# heroku/cli architecture

> Architecture diagram of the GitHub repository heroku/cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/heroku/cli
- Repository: https://github.com/heroku/cli

## Overview

##### Project Type & Purpose
- This is an open-source, monorepo-style CLI application (Heroku CLI) implemented in Node.js/TypeScript.
- It uses oclif to parse commands, organizes its functionality into ~200 command modules, and invokes Heroku’s cloud services (REST APIs for apps, addons, pipelines, pg, redis, etc.).
- CI/CD pipelines in GitHub Actions build, test, package, and publish the CLI to NPM, Homebrew, Snap, Windows installers, etc.

##### High-Level Components
A. CLI Runtime (Node.js process)
- Entry point: packages/cli/bin/heroku (JS shim) → oclif command dispatcher (packages/cli/src/index.ts)
- Command modules: packages/cli/src/commands/**/* → each command invokes core libs
- Hook system: prerun, postrun, command_not_found, update hooks in src/hooks
- Global support: autocomplete scripts (bash/zsh/brew), telemetry (packages/cli/src/lib/telemetry), user config

B. Core Libraries
- API client (lib/api.ts): wraps HTTP calls to Heroku Platform API
- Domain libs: addons, apps, auth, ci pipelines, container, domains, pg, redis, spaces, webhooks, etc.
- Utility libs: config, confirmCommand, streamer, colorize, paginator, uuid-validate

C. External Services
- Heroku Platform REST API endpoints
- GitHub API (for pipelines, addons, Ci manifests)
- Docker daemon (for local runs & container commands)
- Local Foreman process for “heroku local”
- Telemetry ingestion endpoint
- Autocomplete script installation (via OS shell)

D. Build & Release Pipeline
- GitHub Actions workflows (.github/workflows/*.yml)
- Release scripts (scripts/release/*), homebrew, snapcraft, Windows installer
- Yarn 3 Workspaces + Lerna for versioning & publishing

##### Architectural Patterns & Principles
- Command-per-file modular design (oclif): each command implements a small, single responsibility.
- Library-backed commands: share common HTTP client, I/O helpers, and domain logic in `src/lib/*`.
- Hook pipeline: instrumentation, telemetry, update notifications inserted via well-defined hook points.
- Monorepo management: Yarn Workspaces + Lerna for consistent versioning and cross-package dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Node.js CLI"
    subgraph "Runtime"
      Entry["Entry Point\npackages/cli/bin/heroku"]:::runtime
      Dispatcher["oclif Dispatcher\npackages/cli/src/index.ts"]:::runtime
      Entry --> Dispatcher
    end

    subgraph "Command Modules"
      Commands["packages/cli/src/commands/**"]:::runtime
    end

    subgraph "Hook System"
      Pre["prerun hooks\npackages/cli/src/hooks/prerun"]:::runtime
      Post["postrun hooks\npackages/cli/src/hooks/postrun"]:::runtime
      Update["update hooks\npackages/cli/src/hooks/update"]:::runtime
      NotFound["command_not_found hooks\npackages/cli/src/hooks/command_not_found"]:::runtime
    end

    subgraph "Autocomplete"
      Autocomplete["packages/cli/autocomplete-scripts/**"]:::runtime
    end

    subgraph "Core Libraries"
      API["API Client\npackages/cli/src/lib/api.ts"]:::core
      TelemetryLib["Telemetry Lib\npackages/cli/src/lib/telemetry"]:::core
      UserConfig["User Config\npackages/cli/src/user-config.ts"]:::core
      GlobalTelem["Global Telemetry Init\npackages/cli/src/global_telemetry.ts"]:::core

      subgraph "Domain Libs"
        Apps["Apps\npackages/cli/src/lib/apps/**"]:::core
        Addons["Addons\npackages/cli/src/lib/addons/**"]:::core
        CI["CI Lib\npackages/cli/src/lib/ci/**"]:::core
        Pipelines["Pipelines Lib\npackages/cli/src/lib/pipelines/**"]:::core
        Container["Container Helper\npackages/cli/src/lib/container/docker_helper.ts"]:::core
        Domains["Domains\npackages/cli/src/lib/domains/**"]:::core
        PG["Postgres\npackages/cli/src/lib/pg/**"]:::core
        Redis["Redis\npackages/cli/src/lib/redis/**"]:::core
        Webhooks["Webhooks\npackages/cli/src/lib/webhooks/**"]:::core
        Sessions["Sessions\npackages/cli/src/lib/sessions/**"]:::core
        Spaces["Spaces\npackages/cli/src/lib/spaces/**"]:::core
        Auth["Auth\npackages/cli/src/lib/authorizations/**"]:::core
      end

      subgraph "Utility Libs"
        Utils["Utils\npackages/cli/src/lib/utils/**"]:::core
        ConfigHelpers["Config Helpers\npackages/cli/src/lib/config/**"]:::core
        Confirm["Confirm Helper\npackages/cli/src/lib/confirmCommand.ts"]:::core
        RunUtils["Streamer/Colorize/Paginator\npackages/cli/src/lib/run/**"]:::core
        UUID["UUID Validate\npackages/cli/src/lib/utils/uuid-validate.ts"]:::core
      end

      LocalForeman["Local Foreman\npackages/cli/src/lib/local/**"]:::core
      GlobalTypes["Global Types\nglobal.d.ts"]:::core
    end

    Dispatcher --> Commands
    Commands -->|invokes| API
    Commands -->|executes| Container
    Commands -->|hooks| Pre
    Pre --> TelemetryLib
    TelemetryLib -->|sends| TelemetryEndpoint

  end

  subgraph "External Services"
    HerokuAPI["Heroku Platform API"]:::external
    GitHubAPI["GitHub API"]:::external
    DockerDaemon["Docker Daemon"]:::external
    TelemetryEndpoint["Telemetry Endpoint"]:::external
    Foreman["Foreman (local)"]:::external
  end

  API -->|"HTTP REST"| HerokuAPI
  CI -->|"calls"| GitHubAPI
  Container -->|"Docker API"| DockerDaemon
  LocalForeman -->|"Local Process"| Foreman

  subgraph "Build & Release Pipeline"
    GHActions["GitHub Actions\n.github/workflows/*.yml"]:::pipeline
    Lerna["Lerna & Yarn Workspaces\nlerna.json/.yarnrc.yml"]:::pipeline
    Scripts["Release Scripts\nscripts/release/**"]:::pipeline
    PostRelease["Post-release Scripts\nscripts/postrelease/**"]:::pipeline

    GHActions --> Lerna
    GHActions --> Scripts
    Scripts --> PostRelease
    Lerna -.-> Scripts
  end

  classDef runtime fill:#add8e6,stroke:#000;
  classDef core fill:#90ee90,stroke:#000;
  classDef external fill:#ffa500,stroke:#000;
  classDef pipeline fill:#dda0dd,stroke:#000;
```
