cli()

    Bootstrap and run a CLI application. Registers commands, parses arguments, loads config, runs middleware, and invokes the matched handler.

    Import from maltty.

    import { cli } from 'maltty'

cli({
  name: 'my-app',
  version: '1.0.0',
  description: 'My CLI tool',
  commands: { deploy, migrate },
  middleware: [timing],
  help: {
    header: 'my-app - deploy and migrate with ease',
    footer: 'Docs: https://my-app.dev',
  },
  dirs: { local: '.my-app', global: '.my-app' },
})

    CliOptions

    FieldTypeDefaultDescription
    namestring--CLI name (used for help and config discovery)
    versionstring--CLI version
    descriptionstring--Human-readable description
    commandsstring | CommandMap | Promise<CommandMap> | CommandsConfig--Commands source
    middlewareMiddleware[]--Root middleware stack
    helpCliHelpOptions--Custom help header/footer
    dirsDirsConfig--Directory name overrides
    logLog--Custom log implementation
    promptsPrompts--Custom prompts implementation
    spinnerSpinner--Custom spinner implementation

    CliHelpOptions

    FieldTypeDescription
    headerstringText displayed above help output when the CLI is invoked without a command
    footerstringText displayed below help output on all help screens (e.g., docs URL, bug report link)

    DirsConfig

    Overrides directory names for file-backed stores (auth credentials, config). Both default to .<name> when omitted.

    FieldTypeDefaultDescription
    localstring.<name>Directory name for project-local resolution (<project-root>/<local>)
    globalstring.<name>Directory name for global resolution (~/<global>)

    Commands option

    The commands field accepts several forms:

    FormDescription
    CommandMapStatic object mapping command names to command definitions
    Promise<CommandMap>Async-resolved command map
    stringDirectory path -- triggers autoloading from that directory
    CommandsConfigStructured config with optional order array for display ordering
    (omitted)Loads maltty.config.ts and autoloads from its commands field

    defineConfig()

    Helper for defining a maltty.config.ts file with type checking:

    import { defineConfig } from 'maltty/config'

export default defineConfig({
  build: { out: 'dist' },
})

    Module augmentation

    Extend maltty's interfaces via TypeScript declaration merging for project-wide type safety:

    import type { ConfigType } from 'maltty/config'
import { z } from 'zod'

export const configSchema = z.object({
  apiUrl: z.string().url(),
  org: z.string().min(1),
})

declare module 'maltty' {
  interface MalttyArgs {
    verbose: boolean
  }
  interface MalttyStore {
    token: string
  }
}

declare module 'maltty/config' {
  interface ConfigRegistry extends ConfigType<typeof configSchema> {}
}
    InterfaceModuleAffectsDescription
    MalttyArgsmalttyctx.argsGlobal args merged into every command's args
    ConfigRegistrymaltty/configctx.config.load()Typed config returned by load() result
    MalttyStoremalttyctx.storeGlobal store keys merged into the store type
    StoreMapmalttyctx.storeThe store's full key-value shape -- extend to register typed keys (merges with MalttyStore)

    Sub-exports

    ExportPurpose
    maltty/configConfig loading and validation (createConfigClient)
    maltty/storeFile-backed JSON store (createStore)
    maltty/projectGit root resolution, path utilities (findProjectRoot, isInSubmodule, getParentRepoRoot, resolvePath, resolveLocalPath, resolveGlobalPath)
    maltty/formatStandalone format functions (formatCheck, formatFinding, formatCodeFrame, formatTally, formatDuration)
    maltty/authAuth middleware, credential types, strategies (auth)
    maltty/httpTyped HTTP client middleware (http, createHttpClient)
    maltty/iconsIcon detection and font middleware (icons)
    maltty/reportStructured reporting middleware (report, createReport)
    maltty/testTest utilities (createTestContext, runCommand, runMiddleware, runHandler)
    maltty/uiScreen commands and UI components (screen, Box, Text, Select, useConfig, useMeta, useStore)

    References