@heroku-cli/command

@heroku-cli/command

Version 12.4.0
Published 1 day ago
158 kB
12 dependencies
ISC license

Install

npm i @heroku-cli/command

yarn add @heroku-cli/command

pnpm add @heroku-cli/command

Overview

base class for Heroku CLI commands

Index

Variables

variable ALLOWED_HEROKU_DOMAINS

const ALLOWED_HEROKU_DOMAINS: readonly string[];

variable AppAddonCompletion

const AppAddonCompletion: {
    cacheDuration: number;
    cacheKey(ctx: { flags: { app: any } }): Promise<string>;
    options(ctx: { config: Config; flags?: any }): Promise<string[]>;
};

variable AppCompletion

const AppCompletion: {
    cacheDuration: number;
    options(ctx: { config: Config }): Promise<string[]>;
};

variable AppDynoCompletion

const AppDynoCompletion: {
    cacheDuration: number;
    cacheKey(ctx: { flags: { app: any } }): Promise<string>;
    options(ctx: { config: Config; flags?: any }): Promise<string[]>;
};

variable BuildpackCompletion

const BuildpackCompletion: { options(): Promise<string[]>; skipCache: boolean };

variable CredentialStore

const CredentialStore: {
    readonly LinuxSecretService: 'linux-secret-service';
    readonly MacOSKeychain: 'macos-keychain';
    readonly WindowsCredentialManager: 'windows-credential-manager';
};

variable DynoSizeCompletion

const DynoSizeCompletion: {
    cacheDuration: number;
    options(ctx: { config: Config }): Promise<string[]>;
};

variable FileCompletion

const FileCompletion: { options(): Promise<string[]>; skipCache: boolean };

variable LOCALHOST_DOMAINS

const LOCALHOST_DOMAINS: readonly string[];

variable oneDay

const oneDay: number;

variable PipelineCompletion

const PipelineCompletion: {
    cacheDuration: number;
    options(ctx: { config: Config }): Promise<string[]>;
};

variable ProcessTypeCompletion

const ProcessTypeCompletion: { options(): Promise<string[]>; skipCache: boolean };

variable prompter

const prompter: Prompter;

variable RegionCompletion

const RegionCompletion: {
    cacheDuration: number;
    options(ctx: { config: Config }): Promise<string[]>;
};

variable RemoteCompletion

const RemoteCompletion: { options(): Promise<string[]>; skipCache: boolean };

variable RoleCompletion

const RoleCompletion: { options(): Promise<string[]>; skipCache: boolean };

variable ScopeCompletion

const ScopeCompletion: { options(): Promise<string[]>; skipCache: boolean };

variable SpaceCompletion

const SpaceCompletion: {
    cacheDuration: number;
    options(ctx: { config: Config }): Promise<string[]>;
};

variable StackCompletion

const StackCompletion: {
    cacheDuration: number;
    options(ctx: { config: Config }): Promise<string[]>;
};

variable StageCompletion

const StageCompletion: { options(): Promise<string[]>; skipCache: boolean };

variable TeamCompletion

const TeamCompletion: {
    cacheDuration: number;
    options(ctx: { config: Config }): Promise<string[]>;
};

variable vars

const vars: Vars;

variable yubikey

const yubikey: {
    disable: () => void;
    enable: () => void;
    platform: NodeJS.Platform;
};

Functions

function configRemote

configRemote: () => string | undefined;

function deleteLoginState

deleteLoginState: (dataDir: string) => Promise<void>;

function getAuth

getAuth: (
    account: string | undefined,
    host: string,
    service?: string
) => Promise<AuthEntry>;

Retrieves authentication credentials from the native credential store (if available) or .netrc file.
Parameter account
User's account (email), or undefined to search for account
Parameter host
Hostname for netrc lookup (e.g., 'api.heroku.com')
Parameter service
Service name (defaults to 'heroku-cli')
Returns
Promise that resolves with the authentication account and token.
Throws
Error if no credentials are found in either location.

function getCredentialHandler

getCredentialHandler: (
    store: CredentialStore
) => LinuxHandler | MacOSHandler | WindowsHandler;

Factory function to create the appropriate credential handler based on platform.
Parameter store
The type of credential store to use
Returns
A handler instance for the specified store

function getGitRemotes

getGitRemotes: (onlyRemote: string | undefined) => IGitRemotes[];

function getNativeCredentialStore

getNativeCredentialStore: () => CredentialStore | null;

Native credential backend for this platform (Keychain, Secret Service, Windows vault). Ignores HEROKU_NETRC_WRITE so logout can clear credentials written before that mode was used.

function getStorageConfig

getStorageConfig: () => StorageConfig;

Determines whether to use OS-native credential storage, .netrc file, or both.
HEROKU_NETRC_WRITE=true alone selects legacy netrc-only reads/writes (no native store on the primary path). HEROKU_NATIVE_STORE_WRITE=true skips .netrc on the primary path so the OS native store (Keychain, Secret Service, Windows Credential Manager) can be tested in isolation. When both are true, credentials use the native store and .netrc (dual path).
Returns
Object containing storage configuration
Example 1
const config = getStorageConfig() if (config.credentialStore === CredentialStore.MacOSKeychain) { // Use macOS handler } if (config.useNetrc) { // Also use netrc handler }

function herokuGet

herokuGet: (resource: string, ctx: { config: Config }) => Promise<string[]>;

function listKeychainAccounts

listKeychainAccounts: (service?: string) => Promise<string[]>;

Lists all accounts stored in the native credential store for a given service.
Parameter service
Service name (defaults to 'heroku-cli')
Returns
Array of account names, or empty array if no native credential store is available

function parse

parse: (body: string) => MachinesWithTokens;

Parses a netrc file body into a structured MachinesWithTokens object. Handles both inline and multiline machine definitions, including comments.
Parameter body
The raw string content of a netrc file
Returns
A proxied MachinesWithTokens object containing all parsed machine entries

function readLoginState

readLoginState: (dataDir: string) => Promise<LoginState | undefined>;

function removeAuth

removeAuth: (
    account: string | undefined,
    hosts: string[],
    service?: string
) => Promise<void>;

Removes authentication credentials from the platform native store (when present) and .netrc. Uses getNativeCredentialStore so legacy HEROKU_NETRC_WRITE-only mode does not skip Keychain/vault cleanup after a mixed login.
Parameter account
User's account (email), or undefined when using HEROKU_API_KEY only (native removal is skipped)
Parameter hosts
Hostname(s) for netrc storage (e.g., ['api.heroku.com'])
Parameter service
Service name (defaults to 'heroku-cli')
Returns
Promise that resolves when credentials are removed

function saveAuth

saveAuth: (
    account: string,
    token: string,
    hosts: string[],
    service?: string
) => Promise<void>;

Saves authentication credentials to the native credential store (if available) and .netrc file.
Parameter account
User's account (email)
Parameter token
Authentication token
Parameter hosts
Hostname(s) for netrc storage (e.g., ['api.heroku.com'])
Parameter service
Service name (defaults to 'heroku-cli')
Returns
Promise that resolves when credentials are saved

function writeLoginState

writeLoginState: (dataDir: string, account: string) => Promise<void>;

Classes

class APIClient

class APIClient {}

constructor

constructor(config: Config, options?: IOptions);

property auth

auth: string;

property authPromise

authPromise?: Promise<HTTP<any>>;

property config

protected config: Config;

property defaults

readonly defaults: any;

property http

http: any;

property options

options: IOptions;

property particleboard

readonly particleboard: ParticleboardClient;

property preauthPromises

preauthPromises: { [k: string]: Promise<HTTP<any>> };

property twoFactorMutex

readonly twoFactorMutex: Mutex<string>;

method delete

delete: <T>(url: string, options?: APIClient.Options) => Promise<HTTP<T>>;

method get

get: <T>(url: string, options?: APIClient.Options) => Promise<HTTP<T>>;

method getAuth

getAuth: () => Promise<string | undefined>;

method getAuthEntry

getAuthEntry: () => Promise<AuthEntry | undefined>;

login: (opts?: Login.Options) => Promise<void>;

method logout

logout: () => Promise<void>;

method patch

patch: <T>(url: string, options?: APIClient.Options) => Promise<HTTP<T>>;

method post

post: <T>(url: string, options?: APIClient.Options) => Promise<HTTP<T>>;

method preauth

preauth: (app: string, factor: string) => Promise<HTTP<unknown>>;

method put

put: <T>(url: string, options?: APIClient.Options) => Promise<HTTP<T>>;

method request

request: <T>(url: string, options?: APIClient.Options) => Promise<HTTP<T>>;

method setAuthEntry

setAuthEntry: (entry: AuthEntry | undefined) => void;

method stream

stream: (url: string, options?: APIClient.Options) => Promise<HTTP<unknown>>;

method twoFactorPrompt

twoFactorPrompt: () => Promise<string>;

class Command

abstract class Command extends Base {}

property allowArbitraryFlags

allowArbitraryFlags: boolean;

property baseFlags

static baseFlags: Record<string, any>;

Base flags that includes the prompt flag by default Subclasses can override this to customize base flags

property heroku

readonly heroku: APIClient;

property promptFlagActive

static promptFlagActive: boolean;

Set this to false in a command class to disable the --prompt flag for that command

method baseFlagsWithoutPrompt

static baseFlagsWithoutPrompt: () => Record<string, any>;

Helper function to get baseFlags without the prompt flag Use this when you want to remove the prompt flag in a specific command:
Example 1
export default class MyCommand extends Command { static baseFlags = Command.baseFlagsWithoutPrompt() static flags = { ... } }

method init

init: () => Promise<void>;

method isPromptModeActive

protected isPromptModeActive: () => boolean;

Returns whether prompt mode is active for this command. False if the command has opted out (static promptFlagActive = false) or if the prompt flag is not in baseFlags.

method parse

protected parse: (options?: any, argv?: string[]) => Promise<any>;

class Git

class Git {}

property remotes

readonly remotes: IGitRemote[];

method exec

exec: (cmd: string) => string;

class HerokuAPIError

class HerokuAPIError extends CLIError {}

constructor

constructor(httpError: HTTPError);

property body

body: IHerokuAPIErrorOptions;

property http

http: HTTPError;

class LinuxHandler

class LinuxHandler {}

Handles credential storage, removal, and retrieval using the Linux Secret Service API. Uses the secret-tool command-line utility (part of libsecret) to interact with desktop keyrings.

method getAuth

getAuth: (account: string, service: string) => string;

Retrieves the authentication token from the Linux keyring.
Parameter account
The account login to use (e.g. 'test@example.com')
Parameter service
The service name to use
Returns
The stored authentication token.
Throws
Error if the token is not found or retrieval fails.

method listAccounts

listAccounts: (service: string) => string[];

Lists all accounts stored in the Linux keyring for a given service.
Parameter service
The service name to search for
Returns
Array of account names found for the service
Throws
Error if the search operation fails

method removeAuth

removeAuth: (account: string, service: string) => void;

Removes the authentication token from the Linux keyring.
Parameter account
The account login to use (e.g. 'test@example.com')
Parameter service
The service name to use
Returns
void
Throws
Error if the removal operation fails.

method saveAuth

saveAuth: (auth: KeychainAuthEntry) => void;

Saves an authentication entry to the Linux keyring. If a credential with the same attributes already exists, it is updated with the new token.
Parameter auth
The authentication entry containing account and token information to store.
Returns
void
Throws
Error if the save operation fails.

class MacOSHandler

class MacOSHandler {}

Handles credential storage, removal, and retrieval using the macOS Keychain. Uses the macOS security command-line tool to interact with the Keychain.

method getAuth

getAuth: (account: string, service: string) => string;

Retrieves the authentication token from macOS Keychain.
Parameter account
The account login to use (e.g. 'test@example.com')
Parameter service
The service name to use
Returns
The stored authentication token.
Throws
Error if the token is not found or retrieval fails.

method listAccounts

listAccounts: (service: string) => string[];

Lists all accounts stored in macOS Keychain for a given service.
Parameter service
The service name to search for
Returns
Array of account names found for the service
Throws
Error if the search operation fails

method removeAuth

removeAuth: (account: string, service: string) => void;

Removes the authentication token from macOS Keychain.
Parameter account
The account login to use (e.g. 'test@example.com')
Parameter service
The service name to use
Returns
void
Throws
Error if the removal operation fails.

method saveAuth

saveAuth: (auth: KeychainAuthEntry) => void;

Saves an authentication entry to macOS Keychain. If a credential with the same name already exists, it is updated with the new token.
Parameter auth
The authentication entry containing account and token information to store.
Returns
void
Throws
Error if the save operation fails.

class Mutex

class Mutex<T> {}

method dequeue

dequeue: () => Promise<void> | undefined;

method execute

execute: (record: Record<T>) => Promise<void>;

method synchronize

synchronize: (task: Task<T>) => Promise<T>;

class Netrc

class Netrc {}

constructor

constructor(file?: string);

Creates a new Netrc instance.
Parameter file
Optional path to the netrc file. If not provided, uses the default location.

property file

file: string;

property machines

machines: MachinesWithTokens;

method load

load: () => Promise<never | void>;

Asynchronously loads and parses the netrc file. Handles both plain text and GPG-encrypted files.
Returns
A promise that resolves when loading is complete, or throws on error

method loadSync

loadSync: () => never | void;

Synchronously loads and parses the netrc file. Handles both plain text and GPG-encrypted files.
Returns
void, or throws on error

method save

save: () => Promise<void>;

Asynchronously saves the current machines to the netrc file. Handles GPG encryption if the file has a .gpg extension.
Returns
A promise that resolves when saving is complete

method saveSync

saveSync: () => void;

Synchronously saves the current machines to the netrc file. Handles GPG encryption if the file has a .gpg extension.
Returns
void, or throws on error

class NetrcHandler

class NetrcHandler {}

constructor

constructor(file?: string);

Parameter file
Optional netrc path; otherwise uses the default location.

property netrc

readonly netrc: Netrc;

method getAuth

getAuth: (
    host: string
) => Promise<{
    [key: string]: string;
    account?: string;
    login?: string;
    password?: string;
}>;

Retrieves authentication credentials for a given host.
Parameter host
The hostname to retrieve credentials for.
Returns
The authentication entry for the host, or undefined if not found.

method removeAuth

removeAuth: (host: string) => Promise<void>;

Removes authentication credentials for a given host.
Parameter host
The hostname to remove credentials for.
Returns
A promise that resolves when the credentials are removed.

method removeAuthForHosts

removeAuthForHosts: (hosts: string[]) => Promise<void>;

Removes credentials for multiple hosts with a single netrc load/save.

method saveAuth

saveAuth: (auth: NetrcAuthEntry, host: string) => Promise<void>;

Saves authentication credentials for a given host.
Parameter auth
The authentication entry containing login and password.
Parameter host
The hostname to save credentials for.
Returns
A promise that resolves when the credentials are saved.

method saveAuthForHosts

saveAuthForHosts: (auth: NetrcAuthEntry, hosts: string[]) => Promise<void>;

Saves the same credentials for multiple hosts with a single netrc load/save.

class ParticleboardClient

class ParticleboardClient {}

constructor

constructor(config: Config);

property auth

auth: string;

property config

protected config: Config;

property defaults

readonly defaults: any;

property http

http: any;

method get

get: <T>(url: string, options?: HTTPRequestOptions) => Promise<HTTP<T>>;

class Vars

class Vars {}

property apiHost

readonly apiHost: string;

property apiUrl

readonly apiUrl: string;

property envGitHost

readonly envGitHost: string;

property envHost

readonly envHost: string;

property envParticleboardUrl

readonly envParticleboardUrl: string;

property gitHost

readonly gitHost: string;

property gitPrefixes

readonly gitPrefixes: string[];

property host

readonly host: string;

property httpGitHost

readonly httpGitHost: string;

property particleboardUrl

readonly particleboardUrl: string;

class WindowsHandler

class WindowsHandler {}

Handles credential storage and retrieval using the Windows Credential Manager. Uses PowerShell commands to interact with the Windows.Security.Credentials.PasswordVault API.

method getAuth

getAuth: (account: string, service: string) => string;

Retrieves the authentication token from Windows Credential Manager.
Parameter account
The account login to use (e.g. 'test@example.com')
Parameter service
The service name to use
Returns
The stored authentication token.
Throws
Error if the token is not found or retrieval fails.

method listAccounts

listAccounts: (service: string) => string[];

Lists all accounts stored in Windows Credential Manager for a given service.
Parameter service
The service name to search for
Returns
Array of account names found for the service
Throws
Error if the search operation fails

method removeAuth

removeAuth: (account: string, service: string) => void;

Removes the authentication token from Windows Credential Manager.
Parameter account
The account login to use (e.g. 'test@example.com')
Parameter service
The service name to use
Returns
void
Throws
Error if the removal operation fails.

method saveAuth

saveAuth: (auth: KeychainAuthEntry) => void;

Saves an authentication entry to Windows Credential Manager. If a credential with the same name already exists, it is removed before saving the new one.
Parameter auth
The authentication entry containing account and token information to store.
Returns
void
Throws
Error if the save operation fails.

Interfaces

interface IDelinquencyConfig

interface IDelinquencyConfig {}

property fetch_delinquency

fetch_delinquency: boolean;

property fetch_url

fetch_url?: string;

property resource_type

resource_type?: 'account' | 'team';

property warning_shown

warning_shown: boolean;

interface IDelinquencyInfo

interface IDelinquencyInfo {}

property scheduled_deletion_time

scheduled_deletion_time?: null | string;

property scheduled_suspension_time

scheduled_suspension_time?: null | string;

interface IGitRemote

interface IGitRemote {}

property name

name: string;

property url

url: string;

interface IGitRemotes

interface IGitRemotes {}

property app

app: string;

property remote

remote: string;

interface IHerokuAPIErrorOptions

interface IHerokuAPIErrorOptions {}

property app

app?: {
    id: string;
    name: string;
};

property id

id?: string;

property message

message?: string;

property resource

resource?: string;

property url

url?: string;

interface IOptions

interface IOptions {}

property debug

debug?: boolean;

property debugHeaders

debugHeaders?: boolean;

property preauth

preauth?: boolean;

property required

required?: boolean;

Type Aliases

type AuthEntry

type AuthEntry = {
    account: string | undefined;
    token: string | undefined;
};

type CredentialStore

type CredentialStore = (typeof CredentialStore)[keyof typeof CredentialStore];

type KeychainAuthEntry

type KeychainAuthEntry = {
    account: string;
    service: string;
    token: string;
};

type Machines

type Machines = {
    [key: string]: {
        [key: string]: string | undefined;
        account?: string;
        login?: string;
        password?: string;
    };
};

type MachinesWithTokens

type MachinesWithTokens = Machines & {
    _tokens?: Token[];
};

type MachineToken

type MachineToken = {
    comment?: string;
    host: string;
    internalWhitespace: string;
    pre?: string;
    props: {
        [key: string]: {
            comment?: string;
            value: string;
        };
    };
    type: 'machine';
};

type NetrcAuthEntry

type NetrcAuthEntry = {
    login: string;
    password: string;
};

type PromiseReject

type PromiseReject = (reason?: any) => void;

type PromiseResolve

type PromiseResolve<T> = (value: PromiseLike<T> | T) => void;

type Record

type Record<T> = [Task<T>, PromiseResolve<T>, PromiseReject];

type StorageConfig

type StorageConfig = {
    credentialStore: CredentialStore | null;
    useNetrc: boolean;
};

type Task

type Task<T> = () => Promise<T>;

type Token

type Token =
    | MachineToken
    | {
          content: string;
          type: 'other';
      };

Namespaces

namespace APIClient

namespace APIClient {}

interface Options

interface Options extends HTTPRequestOptions {}

property retryAuth

retryAuth?: boolean;

namespace flags

module 'lib/flags/index.d.ts' {}

variable app

const app: any;

variable boolean

const boolean: any;

variable custom

const custom: any;

variable directory

const directory: any;

variable file

const file: any;

variable integer

const integer: any;

variable option

const option: any;

variable org

const org: any;

variable pipeline

const pipeline: any;

variable remote

const remote: any;

variable string

const string: any;

variable team

const team: any;

variable url

const url: any;

function noWrap

noWrap: (options?: {}) => any;

Dependencies (12)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@heroku-cli/command.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@heroku-cli/command)

HTML

<a href="https://www.jsdocs.io/package/@heroku-cli/command"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 1 day ago.
Package analyzed in 3886 ms.
Missing or incorrect documentation? Open an issue for this package.

@heroku-cli/command

Install

Overview

Index

Variables

Functions

Classes

Interfaces

Type Aliases

Namespaces

Variables

variable ALLOWED_HEROKU_DOMAINS

variable AppAddonCompletion

variable AppCompletion

variable AppDynoCompletion

variable BuildpackCompletion

variable CredentialStore

variable DynoSizeCompletion

variable FileCompletion

variable LOCALHOST_DOMAINS

variable oneDay

variable PipelineCompletion

variable ProcessTypeCompletion

variable prompter

variable RegionCompletion

variable RemoteCompletion

variable RoleCompletion

variable ScopeCompletion

variable SpaceCompletion

variable StackCompletion

variable StageCompletion

variable TeamCompletion

variable vars

variable yubikey

Functions

function configRemote

function deleteLoginState

function getAuth

Parameter account

Parameter host

Parameter service

Returns

Throws

function getCredentialHandler

Parameter store

Returns

function getGitRemotes

function getNativeCredentialStore

function getStorageConfig

Returns

Example 1

function herokuGet

function listKeychainAccounts

Parameter service

Returns

function parse

Parameter body

Returns

function readLoginState

function removeAuth

Parameter account

Parameter hosts

Parameter service

Returns

function saveAuth

Parameter account

Parameter token

Parameter hosts

Parameter service

Returns

function writeLoginState

Classes

class APIClient

constructor

property auth

property authPromise

property config

property defaults

property http

property options