@boost/cli

An interactive command line program builder, powered by React and Ink.

import { Program } from '@boost/cli';
import BuildCommand from './commands/Build';
import CleanCommand from './commands/Clean';

const program = new Program({
  bin: 'boost',
  name: 'Boost',
  version: '1.2.3',
});

program.register(new BuildCommand());
program.register(new CleanCommand());

await program.runAndExit(process.argv);

Features

• Supports common argument features like commands, options, flags, parameters, and more.
• Export a stand-alone or command-based CLI program binary.
• Write declarative commands with decorators, or imperative commands with static properties.
• Write shorthand proxy commands for small one offs.
• Renders interface using React and Ink at 16 FPS, or output simple strings.
• Outputs beautiful help, usage, error, and index menus.
• Buffers console logs to avoid render tearing.
• Apply middleware to the argv list, or to the parsed arguments.
• Customize output colors using Boost-based terminal themes.

Installation

yarn add @boost/cli react

Documentation

• https://boostlib.dev/docs/cli
• https://boostlib.dev/api/cli

Index

Classes

• Command
• Program

Functions

• Config
• applyMarkdown
• applyStyle
• checkNodeRequirement
• checkPackageOutdated
• formatCommandCall
• formatDescription
• formatType
• formatValue
• getLongestWidth
• groupByCategory
• isArgvSize
• loadTheme
• mapCommandMetadata

Interfaces

• Arguments
• Category
• CommandConfig
• CommandMetadata
• CommandStaticConfig
• Commandable
• Flag
• GlobalOptions
• MultipleOption
• Option
• OptionInitializer
• Param
• ParserOptions
• ProgramContextType
• ProgramOptions
• ProgramStreams
• SingleOption

Namespaces

• Arg

Type Aliases

• ArgList
• Argv
• CLIErrorCode
• Categories
• CategoryItemMap
• CommandConfigMap
• CommandMetadataMap
• CommandPath
• ExitCode
• ExitHandler
• ListType
• Middleware
• MiddlewareArguments
• MiddlewareCallback
• OptionConfig
• OptionConfigMap
• Options
• ParamConfig
• ParamConfigList
• Params
• PartialConfig
• PrimitiveType
• ProgramBootstrap
• RunResult
• ScalarType
• StyleType
• TaskContext
• ThemePalette
• UnknownOptionMap
• ValueType
• Writeable

Variables

• CLIError
• DELIMITER
• EXIT_FAIL
• EXIT_PASS
• INTERNAL_INITIALIZER
• INTERNAL_OPTIONS
• INTERNAL_PARAMS
• INTERNAL_PROGRAM
• LOCALE_FORMAT
• RESERVED_OPTIONS
• SPACING_COL
• SPACING_COL_WIDE
• SPACING_ROW
• VERSION_FORMAT

Type Aliases

ArgList

ArgList: string[]

Argv

Argv: string[]

CLIErrorCode

CLIErrorCode: keyof typeof errors

Categories

Categories: Record<string, Category | string>

CategoryItemMap

CategoryItemMap<T>: Record<string, { items: T[]; name: string }>

Type parameters

• T

CommandConfigMap

CommandConfigMap: Record<string, CommandConfig>

CommandMetadataMap

CommandMetadataMap: Record<string, CommandMetadata>

CommandPath

CommandPath: string

ExitCode

ExitCode: number

ExitHandler

ExitHandler: (error?: Error | string, code?: ExitCode) => void

ListType

ListType: number[] | string[]

Middleware

Middleware: (argv: Argv, parse: MiddlewareCallback, logger: Loggable) => MiddlewareArguments | Promise<MiddlewareArguments>

MiddlewareArguments

MiddlewareArguments: Arguments<GlobalOptions, ArgList>

MiddlewareCallback

MiddlewareCallback: (argv: Argv) => MiddlewareArguments | Promise<MiddlewareArguments>

OptionConfig

OptionConfig: Option<any> & { arity?: number; choices?: PrimitiveType[]; count?: boolean; default?: ValueType; multiple?: boolean }

Abstract type for easier typing.

OptionConfigMap

OptionConfigMap: Record<string, OptionConfig>

Options

Options<T>: MapOptionConfig<Omit<T, keyof GlobalOptions>>

Type parameters

• T: object

ParamConfig

ParamConfig: Param<any>

Abstract type for easier typing.

ParamConfigList

ParamConfigList: ParamConfig[]

Params

Params<T>: MapParamConfig<T>

Type parameters

• T: PrimitiveType[]

PartialConfig

PartialConfig<T>: Omit<T, description | multiple | path | type>

Type parameters

• T

PrimitiveType

PrimitiveType: ScalarType | boolean

ProgramBootstrap

ProgramBootstrap: () => Promise<void> | void

RunResult

RunResult: ReactElement | string | undefined | void

ScalarType

ScalarType: number | string

StyleType

StyleType: default | failure | info | inverted | muted | notice | success | warning

TaskContext

TaskContext<O>: O & { exit: ExitHandler; log: LoggerFunction; rest: string[]; runProgram: (argv: Argv) => Promise<ExitCode>; runTask: <A, R>(task: (this: TaskContext<O>, ...args: A) => R, ...args: A) => R; unknown: UnknownOptionMap }

Type parameters

• O: GlobalOptions = GlobalOptions

ThemePalette

ThemePalette: { [ T in StyleType ]: string }

UnknownOptionMap

UnknownOptionMap: Record<string, string>

ValueType

ValueType: ListType | PrimitiveType

Writeable

Writeable<T>: { -readonly [ P in keyof T ]: T[P] }

Type parameters

• T

Variables

constCLIError

CLIError: new (code: COMMAND_DEFINED | COMMAND_INVALID_REGISTER | COMMAND_INVALID_RUN | COMMAND_INVALID_SUBPATH | COMMAND_MIXED_DEFAULT | COMMAND_MIXED_NONDEFAULT | COMMAND_NO_PROGRAM | COMMAND_NONE_REGISTERED | COMMAND_UNKNOWN | MIDDLEWARE_INVALID | OPTION_RESERVED | PARAMS_RUN_ONLY | REACT_RENDER_NO_NESTED | THEME_UNKNOWN, params?: unknown[]) => Error & ScopedError<COMMAND_DEFINED | COMMAND_INVALID_REGISTER | COMMAND_INVALID_RUN | COMMAND_INVALID_SUBPATH | COMMAND_MIXED_DEFAULT | COMMAND_MIXED_NONDEFAULT | COMMAND_NO_PROGRAM | COMMAND_NONE_REGISTERED | COMMAND_UNKNOWN | MIDDLEWARE_INVALID | OPTION_RESERVED | PARAMS_RUN_ONLY | REACT_RENDER_NO_NESTED | THEME_UNKNOWN> = ...

constDELIMITER

DELIMITER: $ = '$ '

constEXIT_FAIL

EXIT_FAIL: ExitCode = 1

constEXIT_PASS

EXIT_PASS: ExitCode = 0

constINTERNAL_INITIALIZER

INTERNAL_INITIALIZER: typeof INTERNAL_INITIALIZER = ...

constINTERNAL_OPTIONS

INTERNAL_OPTIONS: typeof INTERNAL_OPTIONS = ...

constINTERNAL_PARAMS

INTERNAL_PARAMS: typeof INTERNAL_PARAMS = ...

constINTERNAL_PROGRAM

INTERNAL_PROGRAM: typeof INTERNAL_PROGRAM = ...

constLOCALE_FORMAT

LOCALE_FORMAT: RegExp = ...

constRESERVED_OPTIONS

RESERVED_OPTIONS: string[] = ...

constSPACING_COL

SPACING_COL: 1 = 1

constSPACING_COL_WIDE

SPACING_COL_WIDE: 2 = 2

constSPACING_ROW

SPACING_ROW: 1 = 1

constVERSION_FORMAT

VERSION_FORMAT: RegExp = ...