Interface CliBuilder<TGlobalValues, TGlobalPositionals>

CLI builder for fluent configuration.

interface CliBuilder<
    TGlobalValues = Record<string, never>,
    TGlobalPositionals extends readonly unknown[] = readonly [],
> {
    command<CV, CP extends readonly unknown[]>(
        name: string,
        cmd: Command<CV, CP>,
        options?: string | CommandOptions,
    ): CliBuilder<TGlobalValues, TGlobalPositionals>;
    command<CV, CP extends readonly unknown[]>(
        name: string,
        parser: Parser<CV, CP>,
        handler: HandlerFn<CV & TGlobalValues, CP>,
        options?: string | CommandOptions,
    ): CliBuilder<TGlobalValues, TGlobalPositionals>;
    command<CV, CP extends readonly unknown[]>(
        name: string,
        factory: (
            builder: CliBuilder<TGlobalValues, TGlobalPositionals>,
        ) => CliBuilder<CV, CP>,
        options?: string | CommandOptions,
    ): CliBuilder<TGlobalValues, TGlobalPositionals>;
    defaultCommand(name: string): CliBuilder<TGlobalValues, TGlobalPositionals>;
    defaultCommand<CV, CP extends readonly unknown[]>(
        cmd: Command<CV, CP>,
    ): CliBuilder<TGlobalValues, TGlobalPositionals>;
    defaultCommand<CV, CP extends readonly unknown[]>(
        parser: Parser<CV, CP>,
        handler: HandlerFn<CV & TGlobalValues, CP>,
    ): CliBuilder<TGlobalValues, TGlobalPositionals>;
    globals<V, P extends readonly unknown[]>(
        parser: Parser<V, P>,
    ): CliBuilder<TGlobalValues & V, readonly [TGlobalPositionals, P]>;
    parse(
        args?: string[],
    ): ParseResult<TGlobalValues, TGlobalPositionals> & { command?: string };
    parseAsync(
        args?: string[],
    ): Promise<
        ParseResult<TGlobalValues, TGlobalPositionals> & { command?: string },
    >;
}

Type Parameters

TGlobalValues = Record<string, never>
TGlobalPositionals extends readonly unknown[] = readonly []

Index

Methods

command defaultCommand globals parse parseAsync

Methods

command

command<CV, CP extends readonly unknown[]>(
    name: string,
    cmd: Command<CV, CP>,
    options?: string | CommandOptions,
): CliBuilder<TGlobalValues, TGlobalPositionals>
Register a command with a Command object.

Note: When using this form, the handler only sees command-local types. Use the (parser, handler) form for merged global+command types.
Type Parameters
- CV
- CP extends readonly unknown[]
Parameters
- name: string
- cmd: Command<CV, CP>
- Optionaloptions: string | CommandOptions
Returns CliBuilder<TGlobalValues, TGlobalPositionals>
- Defined in ../home/runner/work/bargs/bargs/src/types.ts:76
command<CV, CP extends readonly unknown[]>(
    name: string,
    parser: Parser<CV, CP>,
    handler: HandlerFn<CV & TGlobalValues, CP>,
    options?: string | CommandOptions,
): CliBuilder<TGlobalValues, TGlobalPositionals>
Register a command with a Parser and handler separately.

This form provides full type inference for merged global + command types. The handler receives TGlobalValues & CV for values.
Type Parameters
- CV
- CP extends readonly unknown[]
Parameters
- name: string
- parser: Parser<CV, CP>
- handler: HandlerFn<CV & TGlobalValues, CP>
- Optionaloptions: string | CommandOptions
Returns CliBuilder<TGlobalValues, TGlobalPositionals>
- Defined in ../home/runner/work/bargs/bargs/src/types.ts:88
command<CV, CP extends readonly unknown[]>(
    name: string,
    factory: (
        builder: CliBuilder<TGlobalValues, TGlobalPositionals>,
    ) => CliBuilder<CV, CP>,
    options?: string | CommandOptions,
): CliBuilder<TGlobalValues, TGlobalPositionals>
Register a nested command group using a factory function.

This form provides full type inference - the factory receives a builder that already has parent globals typed, so all nested command handlers see the merged types.
Type Parameters
- CV
- CP extends readonly unknown[]
Parameters
- name: string
- factory: (builder: CliBuilder<TGlobalValues, TGlobalPositionals>) => CliBuilder<CV, CP>
- Optionaloptions: string | CommandOptions
Returns CliBuilder<TGlobalValues, TGlobalPositionals>
Example
```
bargs('main')
  .globals(opt.options({ verbose: opt.boolean() }))
  .command(
    'remote',
    (remote) =>
      remote.command('add', addParser, ({ values }) => {
        // values.verbose is typed correctly!
      }),
    'Manage remotes',
  );
```
- Defined in ../home/runner/work/bargs/bargs/src/types.ts:117

defaultCommand

defaultCommand(name: string): CliBuilder<TGlobalValues, TGlobalPositionals>
Set the default command by name (must be registered first).
Parameters
- name: string
Returns CliBuilder<TGlobalValues, TGlobalPositionals>
- Defined in ../home/runner/work/bargs/bargs/src/types.ts:128
defaultCommand<CV, CP extends readonly unknown[]>(
cmd: Command<CV, CP>,
): CliBuilder<TGlobalValues, TGlobalPositionals>
Set the default command with a Command object.

Note: When using this form, the handler only sees command-local types. Use the (parser, handler) form for merged global+command types.
Type Parameters
- CV
- CP extends readonly unknown[]
Parameters
- cmd: Command<CV, CP>
Returns CliBuilder<TGlobalValues, TGlobalPositionals>
- Defined in ../home/runner/work/bargs/bargs/src/types.ts:136
defaultCommand<CV, CP extends readonly unknown[]>(
parser: Parser<CV, CP>,
handler: HandlerFn<CV & TGlobalValues, CP>,
): CliBuilder<TGlobalValues, TGlobalPositionals>
Set the default command with a Parser and handler separately.

This form provides full type inference for merged global + command types. The handler receives TGlobalValues & CV for values.
Type Parameters
- CV
- CP extends readonly unknown[]
Parameters
- parser: Parser<CV, CP>
- handler: HandlerFn<CV & TGlobalValues, CP>
Returns CliBuilder<TGlobalValues, TGlobalPositionals>
- Defined in ../home/runner/work/bargs/bargs/src/types.ts:146

globals

globals<V, P extends readonly unknown[]>(
parser: Parser<V, P>,
): CliBuilder<TGlobalValues & V, readonly [TGlobalPositionals, P]>
Set or extend global options/transforms that apply to all commands.

When called on a builder that already has globals (e.g., from a factory), the new globals are merged with existing ones.
Type Parameters
- V
- P extends readonly unknown[]
Parameters
- parser: Parser<V, P>
Returns CliBuilder<TGlobalValues & V, readonly [TGlobalPositionals, P]>
- Defined in ../home/runner/work/bargs/bargs/src/types.ts:157

parse

parse(
args?: string[],
): ParseResult<TGlobalValues, TGlobalPositionals> & { command?: string }
Parse arguments synchronously and run handlers.

Throws if any transform or handler returns a Promise.
Parameters
- Optionalargs: string[]
Returns ParseResult<TGlobalValues, TGlobalPositionals> & { command?: string }
Remarks
Early exit scenarios (--help, --version, --completion-script, or invalid/missing commands) will call process.exit() and never return. This is standard CLI behavior.
- Defined in ../home/runner/work/bargs/bargs/src/types.ts:171

parseAsync

parseAsync(
args?: string[],
): Promise<
ParseResult<TGlobalValues, TGlobalPositionals> & { command?: string },
>
Parse arguments asynchronously and run handlers.

Supports async transforms and handlers.
Parameters
- Optionalargs: string[]
Returns Promise<ParseResult<TGlobalValues, TGlobalPositionals> & { command?: string }>
Remarks
Early exit scenarios (--help, --version, --completion-script, or invalid/missing commands) will call process.exit() and never return. This is standard CLI behavior.
- Defined in ../home/runner/work/bargs/bargs/src/types.ts:185

Interface CliBuilder<TGlobalValues, TGlobalPositionals>

Type Parameters

Index

Methods

Methods

command

Type Parameters

Parameters

Returns CliBuilder<TGlobalValues, TGlobalPositionals>

Type Parameters

Parameters

Returns CliBuilder<TGlobalValues, TGlobalPositionals>

Type Parameters

Parameters

Returns CliBuilder<TGlobalValues, TGlobalPositionals>

Example

defaultCommand

Parameters

Returns CliBuilder<TGlobalValues, TGlobalPositionals>

Type Parameters

Parameters

Returns CliBuilder<TGlobalValues, TGlobalPositionals>

Type Parameters

Parameters

Returns CliBuilder<TGlobalValues, TGlobalPositionals>

globals

Type Parameters

Parameters

Returns CliBuilder<TGlobalValues & V, readonly [TGlobalPositionals, P]>

parse

Parameters

Returns ParseResult<TGlobalValues, TGlobalPositionals> & { command?: string }

Remarks

parseAsync

Parameters

Returns Promise<ParseResult<TGlobalValues, TGlobalPositionals> & { command?: string }>

Remarks

Settings

On This Page