API Reference

Complete API reference for the create-bcli-app package.

defineConfig

import { defineConfig } from 'create-bcli-app'

function defineConfig(config: CraftConfig): CraftConfig

Creates a typed configuration object. See Configuration for all options.

defineCommand

import { defineCommand } from 'create-bcli-app'

function defineCommand(def: CommandDefinition): CommandDefinition

Defines a CLI command with args, flags, and a run handler.

interface CommandDefinition {
  name?: string
  description?: string
  args?: Record<string, ArgDefinition>
  flags?: Record<string, FlagDefinition>
  run: (ctx: CommandContext) => Promise<unknown> | unknown
}

defineMiddleware

import { defineMiddleware } from 'create-bcli-app'

function defineMiddleware(def: MiddlewareDefinition): MiddlewareDefinition

Defines a lifecycle hook.

interface MiddlewareDefinition {
  phase: 'init' | 'preRun' | 'postRun' | 'error'
  run: (ctx: CommandContext) => Promise<void> | void
}

definePlugin

import { definePlugin } from 'create-bcli-app'

function definePlugin(def: PluginDefinition): PluginDefinition

Defines a plugin.

interface PluginDefinition {
  name: string
  setup: (config: CraftConfig) => CraftConfig | void
}

CommandContext

Everything passed to a command's run function:

interface CommandContext {
  args: Record<string, string | number | boolean | undefined>
  flags: Record<string, string | number | boolean | undefined>
  globalFlags: Record<string, string | number | boolean | undefined>
  command: ResolvedCommand
  config: CraftConfig
  prompt: PromptAPI
  logger: LoggerAPI
  session: SessionAPI
}

PromptAPI

interface PromptAPI {
  text: (opts: TextOpts) => Promise<string>
  confirm: (opts: ConfirmOpts) => Promise<boolean>
  select: <T>(opts: SelectOpts<T>) => Promise<T>
  multiselect: <T>(opts: MultiSelectOpts<T>) => Promise<T[]>
  password: (opts: PasswordOpts) => Promise<string>
  spinner: (opts: SpinnerOpts) => SpinnerAPI
}

SpinnerAPI

interface SpinnerAPI {
  message: (text: string) => void
  succeed: (text?: string) => void
  fail: (text?: string) => void
  warn: (text?: string) => void
  stop: () => void
}

LoggerAPI

interface LoggerAPI {
  info: (...args: unknown[]) => void
  success: (...args: unknown[]) => void
  warn: (...args: unknown[]) => void
  error: (...args: unknown[]) => void
  debug: (...args: unknown[]) => void
  raw: (...args: unknown[]) => void
  table: (data: Record<string, unknown>[], columns?: ColumnDef[]) => void
}

Theme

interface Theme {
  name: string
  colors: ThemeColors
  spinner: ThemeSpinner
  border: ThemeBorder
  icons: ThemeIcons
}

bcliTest (from bcli/test)

import { bcliTest } from 'create-bcli-app/test'

async function bcliTest(
  command: CommandDefinition,
  rawArgs?: string[],
  overrides?: TestOverrides,
): Promise<BcliTestResult>

See Testing for usage.

builtinThemes

import { builtinThemes } from 'create-bcli-app'

builtinThemes.nord
builtinThemes.dracula
builtinThemes['one-dark']
builtinThemes.minimal

resolveTheme

import { resolveTheme } from 'create-bcli-app'

function resolveTheme(nameOrTheme: string | Theme | undefined): Theme