BARGS

Main entry point for the bargs CLI argument parser.

Provides a combinator-style API for building type-safe CLIs.

Example

import { bargs, opt, pos } from '@boneskull/bargs';

await bargs('my-app', { version: '1.0.0' })
  .globals(opt.options({ verbose: opt.boolean({ aliases: ['v'] }) }))
  .command(
    'greet',
    pos.positionals(pos.string({ name: 'name', required: true })),
    ({ positionals }) => console.log(`Hello, ${positionals[0]}!`),
    'Say hello',
  )
  .parseAsync();

Documents

Architecture
Changelog

Core API

The essential building blocks for creating CLIs with bargs. Start here: bargs() creates a CLI, opt defines options, pos defines positionals.

bargs
CreateOptions
opt
pos

Combinators

Functions for composing and transforming parsers. Use map() to transform results, merge() to combine parsers, and handle() to attach handlers.

handle
map
merge
TransformFn

Transforms

Built-in transform functions for modifying parsed results.

camelCaseValues

Help

Help text generation for CLI applications. Customize help output with themes and formatting options.

generateCommandHelp
generateHelp
HelpConfig

Theming

Styling and color customization for help output. Includes ANSI codes, built-in themes, and custom theme support.

createStyler
StyleFn
ThemeInput
Styler
Theme
ThemeColors
ansi
defaultTheme
themes

Terminal

Terminal feature detection and utilities. Includes hyperlink support detection and URL linkification.

link
linkifyUrls
supportsHyperlinks
stripAnsi

Errors

Custom error classes for bargs.

BargsError
HelpError
ValidationError

Option Types

Type definitions for CLI option configurations.

OptionDef
OptionsSchema
ArrayOption
BooleanOption
CountOption
EnumArrayOption
EnumOption
NumberOption
StringOption

Positional Types

Type definitions for positional argument configurations.

PositionalDef
PositionalsSchema
EnumPositional
NumberPositional
StringPositional
VariadicPositional

Parser Types

Core parser and result types for the combinator pipeline.

HandlerFn
PositionalsTransformFn
ValuesTransformFn
CliBuilder
CliResult
Command
CommandDef
CommandOptions
Parser
ParseResult
TransformsConfig

Type Utilities

Advanced TypeScript utilities for type inference and transformation.