⁓ bargs ⁓

"Ex argumentis, veritas"


by @boneskull

Install

``shell
npm install @boneskull/bargs
`

Why bargs?

Most argument parsers make you choose: either a simple API with weak types, or a complex and overengineered DSL. bargs provides a combinator-style API for building type-safe CLIs—composable schema definitions with full type inference.

> Also: this is the only argument parser I know of that comes with frickin' _themes_. _Themes_, dogg.

Quick Start

A CLI with an optional command and a couple options:

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

await bargs('greet', { version: '1.0.0' })
.globals(
opt.options({
name: opt.string({ default: 'world' }),
loud: opt.boolean({ aliases: ['l'] }),
}),
)
.command(
'say',
pos.positionals(pos.string({ name: 'message', required: true })),
({ positionals, values }) => {
const [message] = positionals;
const greeting = ${message}, ${values.name}!;
console.log(values.loud ? greeting.toUpperCase() : greeting);
},
'Say a greeting',
)
.defaultCommand('say')
.parseAsync();
`

`shell
$ greet Hello --name Alice --loud
HELLO, ALICE!
`

Usage

$3

Each helper returns a fully-typed definition:

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

const verbose = opt.boolean({ aliases: ['v'] });
// Type: BooleanOption & { aliases: ['v'] }

const level = opt.enum(['low', 'medium', 'high'], { default: 'medium' });
// Type: EnumOption<'low' | 'medium' | 'high'> & { default: 'medium' }

const file = pos.string({ name: 'file', required: true });
// Type: StringPositional & { name: 'file', required: true }
`

When you build a CLI with these, the result types flow through automatically—options with defaults or required: true are non-nullable.

$3

Options and positionals can be merged using callable parsers:

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

// Create separate parsers
const options = opt.options({
verbose: opt.boolean({ aliases: ['v'] }),
output: opt.string({ aliases: ['o'], default: 'stdout' }),
});

const positionals = pos.positionals(
pos.string({ name: 'input', required: true }),
);

// Merge them: positionals(options) combines both
const parser = positionals(options);
// Type: Parser<{ verbose: boolean | undefined, output: string }, [string]>
`

$3

For a CLI without subcommands, use .globals() with merged options and positionals, then handle the result yourself:

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

// Merge options and positionals into one parser
// when a positional is variadic, it becomes an array within the result
const parser = pos.positionals(pos.variadic('string', { name: 'text' }))(
opt.options({
uppercase: opt.boolean({ aliases: ['u'], default: false }),
}),
);

const { values, positionals } = await bargs('echo', {
description: 'Echo text to stdout',
version: '1.0.0',
})
.globals(parser)
.parseAsync();

const [words] = positionals;
const text = words.join(' ');
console.log(values.uppercase ? text.toUpperCase() : text);
`

$3

For a CLI with multiple subcommands:

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

await bargs('tasks', {
description: 'A task manager',
version: '1.0.0',
})
.globals(
opt.options({
verbose: opt.boolean({ aliases: ['v'], default: false }),
}),
)
.command(
'add',
// Use merge() to combine positionals with command-specific options
merge(
opt.options({
priority: opt.enum(['low', 'medium', 'high'], { default: 'medium' }),
}),
pos.positionals(pos.string({ name: 'text', required: true })),
),
({ positionals, values }) => {
const [text] = positionals;
console.log(Adding ${values.priority} priority task: ${text});
if (values.verbose) console.log('Verbose mode enabled');
},
'Add a task',
)
.command(
'list',
opt.options({
all: opt.boolean({ default: false }),
}),
({ values }) => {
console.log(values.all ? 'All tasks' : 'Pending tasks');
},
'List tasks',
)
.defaultCommand('list')
.parseAsync();
`

`shell
$ tasks add "Buy groceries" --priority high --verbose
Adding high priority task: Buy groceries
Verbose mode enabled

$ tasks list --all
All tasks
`

$3

Commands can be nested to arbitrary depth. _The only limit is your contempt for your users._ Use the factory pattern:

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

await bargs('git')
.globals(opt.options({ verbose: opt.boolean({ aliases: ['v'] }) }))
// Factory pattern: receives a builder with parent globals already typed
.command(
'remote',
(remote) =>
remote
.command(
'add',
pos.positionals(
pos.string({ name: 'name', required: true }),
pos.string({ name: 'url', required: true }),
),
({ positionals, values }) => {
const [name, url] = positionals;
// values.verbose is fully typed! (from parent globals)
if (values.verbose) console.log(Adding ${name}: ${url});
},
'Add a remote',
)
.command('remove' / ... /)
.defaultCommand('add'),
'Manage remotes',
)
.command('commit', commitParser, commitHandler) // Regular command
.parseAsync();
`

`shell
$ git --verbose remote add origin https://github.com/...
Adding origin: https://github.com/...

$ git remote remove origin
`

The factory function receives a CliBuilder that already has parent globals typed, so all nested command handlers get full type inference for merged global + command options. See examples/nested-commands.ts for a full example.

API

$3

Create a CLI builder.

| Option | Type | Description |
| ------------- | ------------------- | ------------------------------------------- |
| description | string | Description shown in help |
| version | string | Enables --version flag |
| epilog | string or false | Footer text in help (see Epilog) |
| theme | Theme | Help color theme (see Theming) |

$3

Set global options and transforms that apply to all commands.

`typescript
bargs('my-cli').globals(opt.options({ verbose: opt.boolean() }));
// ...
`

$3

Register a command. The handler receives merged global + command types.

`typescript
.command(
'build',
opt.options({ watch: opt.boolean() }),
({ values }) => {
// values has both global options AND { watch: boolean }
console.log(values.verbose, values.watch);
},
'Build the project',
)
`

$3

Register a nested command group using a factory function. The factory receives a builder that already has parent globals typed, giving full type inference in nested handlers.

`typescript
bargs('main')
.globals(opt.options({ verbose: opt.boolean() }))
.command(
'nested',
(nested) =>
nested
.command('foo', fooParser, ({ values }) => {
// values.verbose is typed correctly!
})
.command('bar', barParser, barHandler),
'Nested commands',
)
.parseAsync();
`

$3

> Or .defaultCommand(parser, handler)

Set the command that runs when no command is specified.

`typescript
// Reference an existing command by name
.defaultCommand('list')

// Or define an inline default
.defaultCommand(
pos.positionals(pos.string({ name: 'file' })),
({ positionals }) => console.log(positionals[0]),
)
`

$3

Parse arguments and execute handlers.

- .parse() - Synchronous. Throws if any transform or handler returns a Promise.
- .parseAsync() - Asynchronous. Supports async transforms and handlers.

`typescript
// Async (supports async transforms/handlers)
const result = await bargs('my-cli').globals(...).parseAsync();
console.log(result.values, result.positionals, result.command);

// Sync (no async transforms/handlers)
const result = bargs('my-cli').globals(...).parse();
`

Option Helpers

`typescript
import { opt } from '@boneskull/bargs';

opt.string({ default: 'value' }); // --name value
opt.number({ default: 42 }); // --count 42
opt.boolean({ aliases: ['v'] }); // --verbose, -v
opt.boolean({ aliases: ['v', 'verb'] }); // --verbose, --verb, -v
opt.enum(['a', 'b', 'c']); // --level a
opt.array('string'); // --file x --file y
opt.array(['low', 'medium', 'high']); // --priority low --priority high
opt.count(); // -vvv → 3
`

$3

| Property | Type | Description |
| ------------- | ---------- | ------------------------------------------------------------------ |
| aliases | string[] | Short (['v'] for -v) or long aliases (['verb'] for --verb) |
| default | varies | Default value (makes the option non-nullable) |
| description | string | Help text description |
| group | string | Groups options under a custom section header |
| hidden | boolean | Hide from --help output |
| required | boolean | Mark as required (makes the option non-nullable) |

$3

Options can have both short (single-character) and long (multi-character) aliases:

`typescript
opt.options({
verbose: opt.boolean({ aliases: ['v', 'verb'] }),
output: opt.string({ aliases: ['o', 'out'] }),
});
`

All of these are equivalent:

`shell
$ my-cli -v # verbose: true
$ my-cli --verb # verbose: true
$ my-cli --verbose # verbose: true
$ my-cli -o file.txt # output: "file.txt"
$ my-cli --out file.txt # output: "file.txt"
$ my-cli --output file.txt # output: "file.txt"
`

For non-array options, using both an alias and the canonical name throws an error:

`shell
$ my-cli --verb --verbose
Error: Conflicting options: --verb and --verbose cannot both be specified
`

For array options, values from all aliases are merged. Single-character aliases and the canonical name are processed first (in command-line order), then multi-character aliases are appended:

`typescript
opt.options({
files: opt.array('string', { aliases: ['f', 'file'] }),
});
`

`shell
$ my-cli --file a.txt -f b.txt --files c.txt


files: ["b.txt", "c.txt", "a.txt"]

(-f and --files first, then --file appended)

`

$3

All boolean options automatically support a negated form --no- to explicitly set the option to false:

`shell
$ my-cli --verbose # verbose: true
$ my-cli --no-verbose # verbose: false
$ my-cli # verbose: undefined (or default)
`

If both --flag and --no-flag are specified, bargs throws an error:

`shell
$ my-cli --verbose --no-verbose
Error: Conflicting options: --verbose and --no-verbose cannot both be specified
`

In help output, booleans with default: true display as --no- (since that's how users would turn them off):

`typescript
opt.options({
colors: opt.boolean({ default: true, description: 'Use colors' }),
});
// Help output shows: --no-colors Use colors [boolean] default: true
`

$3

Create a parser from an options schema:

`typescript
const parser = opt.options({
verbose: opt.boolean({ aliases: ['v'] }),
output: opt.string({ default: 'out.txt' }),
});
// Type: Parser<{ verbose: boolean | undefined, output: string }, []>
`

Positional Helpers

`typescript
import { pos } from '@boneskull/bargs';

pos.string({ required: true }); //
pos.number({ default: 8080 }); // [port]
pos.enum(['dev', 'prod']); // [env]
pos.variadic('string'); // [files...]
`

$3

| Property | Type | Description |
| ------------- | --------- | ------------------------------------------------------ |
| default | varies | Default value |
| description | string | Help text description |
| name | string | Display name in help (defaults to arg0, arg1, ...) |
| required | boolean | Mark as required (shown as vs [name]) |

$3

Create a parser from positional definitions:

`typescript
const parser = pos.positionals(
pos.string({ name: 'source', required: true }),
pos.string({ name: 'dest', required: true }),
);
// Type: Parser<{}, [string, string]>
`

Use variadic for rest arguments (must be last):

`typescript
const parser = pos.positionals(pos.variadic('string', { name: 'files' }));
// Type: Parser<{}, [string[]]>
`

Merging Parsers

Use merge() to combine multiple parsers into one:

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

const combined = merge(
opt.options({
priority: opt.enum(['low', 'medium', 'high'], { default: 'medium' }),
}),
pos.positionals(pos.string({ name: 'task', required: true })),
);
// Type: Parser<{ priority: 'low' | 'medium' | 'high' }, [string]>
`

You can merge as many parsers as needed—options are merged (later overrides earlier), and positionals are concatenated.

Alternatively, parsers can be merged by calling one with the other:

`typescript
const options = opt.options({ priority: opt.enum(['low', 'medium', 'high']) });
const positionals = pos.positionals(
pos.string({ name: 'task', required: true }),
);

// These are equivalent:
const combined1 = positionals(options);
const combined2 = options(positionals);
`

Use whichever style you find more readable.

Transforms

Use map() to transform parsed values before they reach your handler:

`typescript
import { bargs, map, opt } from '@boneskull/bargs';

const globals = map(
opt.options({
config: opt.string(),
verbose: opt.boolean({ default: false }),
}),
({ values, positionals }) => ({
positionals,
values: {
...values,
// Add computed properties
timestamp: new Date().toISOString(),
configLoaded: !!values.config,
},
}),
);

await bargs('my-cli')
.globals(globals)
.command(
'info',
opt.options({}),
({ values }) => {
// values.timestamp and values.configLoaded are available
console.log(values.timestamp);
},
'Show info',
)
.parseAsync();
`

Transforms are fully type-safe—the return type becomes the type available in handlers.

$3

Transforms can be async:

`typescript
const globals = map(
opt.options({ url: opt.string({ required: true }) }),
async ({ values, positionals }) => {
const response = await fetch(values.url);
return {
positionals,
values: {
...values,
data: await response.json(),
},
};
},
);
`

$3

If you prefer camelCase property names instead of kebab-case, use the camelCaseValues transform:

`typescript
import { bargs, map, opt, camelCaseValues } from '@boneskull/bargs';

const { values } = await bargs('my-cli')
.globals(
map(
opt.options({
'output-dir': opt.string({ default: '/tmp' }),
'dry-run': opt.boolean(),
}),
camelCaseValues,
),
)
.parseAsync(['--output-dir', './dist', '--dry-run']);

console.log(values.outputDir); // './dist'
console.log(values.dryRun); // true
`

The camelCaseValues transform:

- Converts all kebab-case keys to camelCase (output-dir → outputDir)
- Preserves keys that are already camelCase or have no hyphens
- Is fully type-safe—TypeScript knows the transformed key names

Epilog

By default, bargs displays your package's homepage and repository URLs (from package.json) at the end of help output. URLs become clickable hyperlinks in supported terminals.

`typescript
// Custom epilog
bargs('my-cli', {
epilog: 'For more info, visit https://example.com',
});

// Disable epilog entirely
bargs('my-cli', { epilog: false });
`

Theming

Customize help output colors with built-in themes or your own:

`typescript
// Use a built-in theme: 'default', 'mono', 'ocean', 'warm'
bargs('my-cli', { theme: 'ocean' });

// Disable colors entirely
bargs('my-cli', { theme: 'mono' });
`

The ansi export provides common ANSI escape codes for styled terminal output:

`typescript
import { ansi } from '@boneskull/bargs';

bargs('my-cli', {
theme: {
colors: {
command: ansi.bold,
flag: ansi.brightCyan,
positional: ansi.magenta,
// ...
},
},
});
`

Available theme color slots:

| Slot | What it styles |
| --------------- | ----------------------------------------------- |
| command | Command names (e.g., init, build) |
| defaultText | The default: label |
| defaultValue | Default value (e.g., false, "hello") |
| description | Description text for options and commands |
| epilog | Footer text (homepage, repository) |
| example | Example code/commands |
| flag | Flag names (e.g., --verbose, -v) |
| positional | Positional argument names (e.g., ) |
| scriptName | CLI name shown in header |
| sectionHeader | Section headers (e.g., USAGE, OPTIONS) |
| type | Type annotations (e.g., [string], [number]) |
| url | URLs (for clickable hyperlinks) |
| usage | The usage line text |

> [!TIP]
> You don't need to specify all color slots. Missing colors fall back to the default theme.

Shell Completion

bargs can generate shell completion scripts for bash, zsh, and fish. Enable it with the completion option:

`typescript
bargs('my-cli', {
completion: true,
version: '1.0.0',
});
`

Then generate and install the completion script for your shell:

$3

`bash


Add to ~/.bashrc (or ~/.bash_profile on macOS)


my-cli --completion-script bash >> ~/.bashrc
source ~/.bashrc
`

$3

`bash


Add to ~/.zshrc

my-cli --completion-script zsh >> ~/.zshrc
source ~/.zshrc

Or save to a file in your $fpath

my-cli --completion-script zsh > ~/.zsh/completions/_my-cli
`

$3

`bash


Save to completions directory


my-cli --completion-script fish > ~/.config/fish/completions/my-cli.fish
`

$3

Once installed, pressing Tab will complete:

- Commands and subcommands (including nested commands and aliases)
- Options (--verbose, -v, --no-verbose for booleans)
- Enum values for options and positionals with defined choices
- Global options at any command level

`shell
$ my-cli
build test lint

$ my-cli build --target
dev staging prod

$ my-cli --
--verbose --config --help --version
`

See examples/completion.ts for a complete example.

Advanced Usage

$3

bargs exports some Error subclasses:

`typescript
import {
bargs,
BargsError,
HelpError,
ValidationError,
} from '@boneskull/bargs';

try {
await bargs('my-cli').parseAsync();
} catch (error) {
if (error instanceof ValidationError) {
// Config validation failed (e.g., invalid schema)
// i.e., "you screwed up"
console.error(Config error at "${error.path}": ${error.message});
} else if (error instanceof HelpError) {
// Likely invalid options, command or positionals;
// re-throw to trigger help display
throw error;
} else if (error instanceof BargsError) {
// General bargs error
console.error(error.message);
}
}
`

$3

Generate help text programmatically:

`typescript
import { generateHelp, generateCommandHelp } from '@boneskull/bargs';

// These require the internal config structure—see source for details
const helpText = generateHelp(config);
const commandHelp = generateCommandHelp(config, 'migrate');
`

$3

Create clickable terminal hyperlinks (OSC 8):

`typescript
import { link, linkifyUrls, supportsHyperlinks } from '@boneskull/bargs';

// Check if terminal supports hyperlinks
if (supportsHyperlinks()) {
// Create a hyperlink
console.log(link('Click me', 'https://example.com'));

// Auto-linkify URLs in text
console.log(linkifyUrls('Visit https://example.com for more info'));
}
`

> [!TIP]
> bargs already automatically links URLs in --help output if the terminal supports hyperlinks.

$3

`typescript
import {
ansi, // ANSI escape codes
createStyler, // Create a styler from a theme
defaultTheme, // The default theme object
stripAnsi, // Remove ANSI codes from string
themes, // All built-in themes
} from '@boneskull/bargs';

// Create a custom styler
const styler = createStyler({ colors: { flag: ansi.green } });
console.log(styler.flag('--verbose'));

// Strip ANSI codes for plain text output
const plain = stripAnsi('\x1b32m--verbose\x1b[0m'); // '--verbose'
`

$3

The handle(parser, fn) function is exported for advanced use cases where you need to create a Command object outside the fluent builder. It's mostly superseded by .command(name, parser, handler).

Dependencies

bargs has zero (0) dependencies. Only Node.js v20+.

Motivation

I've always reached for [yargs in my CLI projects. However, I find myself repeatedly doing the same things; I have a sort of boilerplate in my head, ready to go (requiresArg: true and nargs: 1`, amirite?). I don't want boilerplate in my head. I wanted to distill my chosen subset of yargs' behavior into a composable API. And so bargs was begat.

License

Copyright © 2025 Christopher "boneskull" Hiller. Licensed under the Blue Oak Model License 1.0.0.