@boneskull/bargs 1.0.0 → 3.0.0

package/README.md

@@ -2,7 +2,7 @@
   <a href="/"><img src="./assets/logo.png" width="512px" align="center" alt="bargs: a barg parser"/></a>
   <h1 align="center"><span class="bargs">⁓ bargs ⁓<span></h1>
   <p align="center">
-    <em>“Ex argumentis, veritas”</em>
+    <em>"Ex argumentis, veritas"</em>
     <br/>
     <small>by <a href="https://github.com/boneskull" title="@boneskull on GitHub">@boneskull</a></small>
   </p>
@@ -16,311 +16,253 @@ 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** uses _function helpers_ that instead provide a well-typed and composable API.
+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.
 
-### Type-Safe by Construction
+## Quick Start
 
-Each helper returns a fully-typed option definition:
+A CLI with an optional command and a couple options:
 
 ```typescript
-const verbose = bargs.boolean({ aliases: ['v'] });
-// Type: BooleanOption & { aliases: ['v'] }
+import { bargs, opt, pos } from '@boneskull/bargs';
+
+await bargs
+  .create('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();
+```
 
-const level = bargs.enum(['low', 'medium', 'high'], { default: 'medium' });
-// Type: EnumOption<'low' | 'medium' | 'high'> & { default: 'medium' }
+```shell
+$ greet Hello --name Alice --loud
+HELLO, ALICE!
 ```
 
-When you pass these to `bargs()`, the result is always well-typed; options with defaults or `required: true` are non-nullable.
+## Usage
 
-### Composable
+### Type-Safe by Construction
 
-Since helpers are just functions returning objects, composition is trivial:
+Each helper returns a fully-typed definition:
 
 ```typescript
-// Shared options across commands
-const verboseOpt = { verbose: bargs.boolean({ aliases: ['v'] }) };
-const outputOpt = {
-  output: bargs.string({ aliases: ['o'], default: 'stdout' }),
-};
-
-// Merge with spread
-const result = bargs({
-  name: 'tool',
-  options: {
-    ...verboseOpt,
-    ...outputOpt,
-    format: bargs.enum(['json', 'text']),
-  },
-});
-```
+import { opt, pos } from '@boneskull/bargs';
 
-Or use `bargs.options()` and `bargs.positionals()`:
+const verbose = opt.boolean({ aliases: ['v'] });
+// Type: BooleanOption & { aliases: ['v'] }
 
-```typescript
-// Throws if aliases collide
-const sharedOpts = bargs.options(verboseOpt, outputOpt);
+const level = opt.enum(['low', 'medium', 'high'], { default: 'medium' });
+// Type: EnumOption<'low' | 'medium' | 'high'> & { default: 'medium' }
 
-// Combine positionals with type inference
-const sharedPos = bargs.positionals(
-  bargs.stringPos({ name: 'input', required: true }),
-  bargs.stringPos({ name: 'output' }),
-);
+const file = pos.string({ name: 'file', required: true });
+// Type: StringPositional & { name: 'file', required: true }
 ```
 
-> [!TIP]
-> Helper functions are provided for convenience and composability, but you can also just use raw object literals. See the ["tasks" example](./examples/tasks.ts) to see how.
-
-### Zero (0) Dependencies
+When you build a CLI with these, the result types flow through automatically—options with defaults or `required: true` are non-nullable.
 
-Only Node.js v22+.
+### Composable
 
-## Quick Start
+Options and positionals can be merged using callable parsers:
 
 ```typescript
-import { bargs } from '@boneskull/bargs';
+import { opt, pos } from '@boneskull/bargs';
 
-const result = bargs({
-  name: 'greet',
-  options: {
-    name: bargs.string({ default: 'world' }),
-    loud: bargs.boolean({ aliases: ['l'] }),
-  },
+// Create separate parsers
+const options = opt.options({
+  verbose: opt.boolean({ aliases: ['v'] }),
+  output: opt.string({ aliases: ['o'], default: 'stdout' }),
 });
 
-const greeting = `Hello, ${result.values.name}!`;
-console.log(result.values.loud ? greeting.toUpperCase() : greeting);
-```
+const positionals = pos.positionals(
+  pos.string({ name: 'input', required: true }),
+);
 
-```shell
-$ greet --name Alice --loud
-HELLO, ALICE!
+// Merge them: positionals(options) combines both
+const parser = positionals(options);
+// Type: Parser<{ verbose: boolean | undefined, output: string }, [string]>
 ```
 
-## Sync vs Async
+### Simple CLI
 
-**`bargs()`** runs synchronously. If a handler returns a `Promise`, it will break and you will be sorry.
+For a CLI without subcommands, use `.globals()` with merged options and positionals, then handle the result yourself:
 
 ```typescript
-// Sync - no await needed
-const result = bargs({
-  name: 'my-cli',
-  options: { verbose: bargs.boolean() },
-  handler: ({ values }) => {
-    console.log('Verbose:', values.verbose);
-  },
-});
-```
-
-Instead, use **`bargsAsync()`**:
-
-```typescript
-import { bargsAsync } from '@boneskull/bargs';
+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 }),
+  }),
+);
 
-// Async - handlers can return Promises
-const result = await bargsAsync({
-  name: 'my-cli',
-  options: { url: bargs.string({ required: true }) },
-  handler: async ({ values }) => {
-    const response = await fetch(values.url);
-    console.log(await response.text());
-  },
-});
+const { values, positionals } = await bargs
+  .create('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);
 ```
 
-## Commands
+### Command-Based CLI
 
-Define subcommands with `bargs.command()`:
+For a CLI with multiple subcommands:
 
 ```typescript
-bargs({
-  name: 'db',
-  commands: {
-    migrate: bargs.command({
-      description: 'Run database migrations',
-      options: { dry: bargs.boolean({ aliases: ['n'] }) },
-      handler: ({ values }) => {
-        console.log(values.dry ? 'Dry run...' : 'Migrating...');
-      },
+import { bargs, merge, opt, pos } from '@boneskull/bargs';
+
+await bargs
+  .create('tasks', {
+    description: 'A task manager',
+    version: '1.0.0',
+  })
+  .globals(
+    opt.options({
+      verbose: opt.boolean({ aliases: ['v'], default: false }),
     }),
-    seed: bargs.command({
-      description: 'Seed the database',
-      positionals: [bargs.stringPos({ required: true })],
-      handler: ({ positionals }) => {
-        const [file] = positionals;
-        console.log(`Seeding from ${file}...`);
-      },
+  )
+  .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
-$ db migrate --dry
-Dry run...
+$ tasks add "Buy groceries" --priority high --verbose
+Adding high priority task: Buy groceries
+Verbose mode enabled
 
-$ db seed data.sql
-Seeding from data.sql...
+$ tasks list --all
+All tasks
 ```
 
-### Default Handler
+## API
 
-For command-based CLIs, use `defaultHandler` to handle the case when no command is provided:
-
-```typescript
-bargs({
-  name: 'git',
-  commands: {
-    /* ... */
-  },
-  // Run 'status' when no command given
-  defaultHandler: 'status',
-});
+### `bargs.create(name, options?)`
 
-// Or provide a custom handler
-bargs({
-  name: 'git',
-  commands: {
-    /* ... */
-  },
-  defaultHandler: ({ values }) => {
-    console.log('Run "git --help" for usage');
-  },
-});
-```
+Create a CLI builder.
 
-## Transforms
+| Option        | Type                | Description                                 |
+| ------------- | ------------------- | ------------------------------------------- |
+| `description` | `string`            | Description shown in help                   |
+| `version`     | `string`            | Enables `--version` flag                    |
+| `epilog`      | `string` or `false` | Footer text in help (see [Epilog](#epilog)) |
+| `theme`       | `Theme`             | Help color theme (see [Theming](#theming))  |
 
-Transforms let you modify parsed values and positionals before they reach your handler. This is useful for:
+### `.globals(parser)`
 
-- Loading and merging configuration files
-- Adding computed/derived values
-- Validating or normalizing inputs
-- Async operations like file system checks
+Set global options and transforms that apply to all commands.
 
 ```typescript
-const result = await bargsAsync({
-  name: 'my-cli',
-  options: {
-    config: bargsAsync.string({ aliases: ['c'] }),
-    verbose: bargsAsync.boolean({ default: false }),
-  },
-  positionals: [bargsAsync.variadic('string', { name: 'files' })],
-  transforms: {
-    // Transform option values
-    values: (values) => {
-      // Load config file if specified
-      const fileConfig = values.config
-        ? JSON.parse(readFileSync(values.config, 'utf8'))
-        : {};
-
-      return {
-        ...fileConfig,
-        ...values,
-        // Add computed values
-        timestamp: new Date().toISOString(),
-      };
-    },
-    // Transform positionals
-    positionals: (positionals) => {
-      const [files] = positionals;
-      // Filter to only existing files
-      return [files.filter((f) => existsSync(f))];
-    },
-  },
-  handler: ({ values, positionals }) => {
-    // values.timestamp is available here
-    // positionals contains only valid files
-  },
-});
+bargs.create('my-cli').globals(opt.options({ verbose: opt.boolean() }));
+// ...
 ```
 
-### Transform Properties
-
-Transforms are akin to yargs' "middleware". They execute after parsing but before the handler (if present). Transforms should also be used in place of yargs' "coerce" option.
-
-| Property      | Type                                      | Description                       |
-| ------------- | ----------------------------------------- | --------------------------------- |
-| `values`      | `(values) => TransformedValues`           | Transform parsed option values    |
-| `positionals` | `(positionals) => TransformedPositionals` | Transform parsed positional tuple |
+### `.command(name, parser, handler, description?)`
 
-Both transforms can be sync or async. The return type of each transform becomes the type available in your handler.
-
-### Type Inference
-
-Transforms are fully type-safe. TypeScript infers the transformed types:
+Register a command. The handler receives merged global + command types.
 
 ```typescript
-bargs({
-  name: 'example',
-  options: { count: bargs.number() },
-  transforms: {
-    values: (values) => ({
-      ...values,
-      doubled: (values.count ?? 0) * 2, // Add computed property
-    }),
+.command(
+  'build',
+  opt.options({ watch: opt.boolean() }),
+  ({ values }) => {
+    // values has both global options AND { watch: boolean }
+    console.log(values.verbose, values.watch);
   },
-  handler: ({ values }) => {
-    console.log(values.doubled); // number - fully typed!
-  },
-});
+  'Build the project',
+)
 ```
 
-## Configuration
+### `.defaultCommand(name)` or `.defaultCommand(parser, handler)`
 
-### Config Properties
-
-| Property      | Type                  | Description                                                  |
-| ------------- | --------------------- | ------------------------------------------------------------ |
-| `name`        | `string`              | CLI name (required)                                          |
-| `description` | `string`              | Description shown in help                                    |
-| `version`     | `string`              | Enables `--version` flag                                     |
-| `options`     | `OptionsSchema`       | Named options (`--flag`)                                     |
-| `positionals` | `PositionalsSchema`   | Positional arguments                                         |
-| `commands`    | `Record<string, ...>` | Subcommands                                                  |
-| `transforms`  | `TransformsConfig`    | Transform values/positionals (see [Transforms](#transforms)) |
-| `handler`     | `Handler`             | Handler function for simple CLIs                             |
-| `epilog`      | `string \| false`     | Footer text in help (see [Epilog](#epilog))                  |
-| `args`        | `string[]`            | Custom args (defaults to `process.argv.slice(2)`)            |
+Set the command that runs when no command is specified.
 
 ```typescript
-bargs({
-  name: 'my-cli',
-  description: 'Does amazing things',
-  version: '1.2.3', // enables --version
-  args: ['--verbose', 'file.txt'], // useful for testing
-  options: {
-    /* ... */
-  },
-});
+// 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]),
+)
 ```
 
-### Runtime Options
+### `.parse(args?)` / `.parseAsync(args?)`
 
-The second argument to `bargs()` or `bargsAsync()` accepts runtime options:
+Parse arguments and execute handlers.
 
-| Property | Type         | Description                                    |
-| -------- | ------------ | ---------------------------------------------- |
-| `theme`  | `ThemeInput` | `--help` Color theme (see [Theming](#theming)) |
+- **`.parse()`** - Synchronous. Throws if any transform or handler returns a Promise.
+- **`.parseAsync()`** - Asynchronous. Supports async transforms and handlers.
 
 ```typescript
-bargs(config, { theme: 'ocean' });
+// Async (supports async transforms/handlers)
+const result = await bargs.create('my-cli').globals(...).parseAsync();
+console.log(result.values, result.positionals, result.command);
+
+// Sync (no async transforms/handlers)
+const result = bargs.create('my-cli').globals(...).parse();
 ```
 
 ## Option Helpers
 
 ```typescript
-bargs.string({ default: 'value' }); // --name value
-bargs.number({ default: 42 }); // --count 42
-bargs.boolean({ aliases: ['v'] }); // --verbose, -v
-bargs.enum(['a', 'b', 'c']); // --level a
-bargs.array('string'); // --file x --file y
-bargs.count(); // -vvv → 3
+import { opt } from '@boneskull/bargs';
+
+opt.string({ default: 'value' }); // --name value
+opt.number({ default: 42 }); // --count 42
+opt.boolean({ aliases: ['v'] }); // --verbose, -v
+opt.enum(['a', 'b', 'c']); // --level a
+opt.array('string'); // --file x --file y
+opt.count(); // -vvv → 3
 ```
 
 ### Option Properties
 
-All option helpers accept these properties:
-
 | Property      | Type       | Description                                      |
 | ------------- | ---------- | ------------------------------------------------ |
 | `aliases`     | `string[]` | Short flags (e.g., `['v']` for `-v`)             |
@@ -330,27 +272,27 @@ All option helpers accept these properties:
 | `hidden`      | `boolean`  | Hide from `--help` output                        |
 | `required`    | `boolean`  | Mark as required (makes the option non-nullable) |
 
-Example:
+### `opt.options(schema)`
+
+Create a parser from an options schema:
 
 ```typescript
-bargs.string({
-  aliases: ['o'],
-  default: 'output.txt',
-  description: 'Output file path',
-  group: 'Output Options',
+const parser = opt.options({
+  verbose: opt.boolean({ aliases: ['v'] }),
+  output: opt.string({ default: 'out.txt' }),
 });
-
-// Hidden options won't appear in help
-bargs.boolean({ hidden: true });
+// Type: Parser<{ verbose: boolean | undefined, output: string }, []>
 ```
 
 ## Positional Helpers
 
 ```typescript
-bargs.stringPos({ required: true }); // <file>
-bargs.numberPos({ default: 8080 }); // [port]
-bargs.enumPos(['dev', 'prod']); // [env]
-bargs.variadic('string'); // [files...]
+import { pos } from '@boneskull/bargs';
+
+pos.string({ required: true }); // <file>
+pos.number({ default: 8080 }); // [port]
+pos.enum(['dev', 'prod']); // [env]
+pos.variadic('string'); // [files...]
 ```
 
 ### Positional Properties
@@ -362,41 +304,116 @@ bargs.variadic('string'); // [files...]
 | `name`        | `string`  | Display name in help (defaults to `arg0`, `arg1`, ...) |
 | `required`    | `boolean` | Mark as required (shown as `<name>` vs `[name]`)       |
 
-Example:
+### `pos.positionals(...defs)`
+
+Create a parser from positional definitions:
 
 ```typescript
-bargs.stringPos({
-  name: 'file',
-  description: 'Input file to process',
-  required: true,
-});
+const parser = pos.positionals(
+  pos.string({ name: 'source', required: true }),
+  pos.string({ name: 'dest', required: true }),
+);
+// Type: Parser<{}, [string, string]>
 ```
 
-Positionals are defined as an array and accessed by index:
+Use `variadic` for rest arguments (must be last):
 
 ```typescript
-const result = bargs({
-  name: 'cp',
-  positionals: [
-    bargs.stringPos({ required: true }), // source
-    bargs.stringPos({ required: true }), // destination
-  ],
-});
+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 [source, dest] = result.positionals;
-console.log(`Copying ${source} to ${dest}`);
+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]>
 ```
 
-Use `variadic` for rest arguments (must be last):
+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 result = bargs({
-  name: 'cat',
-  positionals: [bargs.variadic('string')],
-});
+const options = opt.options({ priority: opt.enum(['low', 'medium', 'high']) });
+const positionals = pos.positionals(
+  pos.string({ name: 'task', required: true }),
+);
 
-const [files] = result.positionals; // string[]
-files.forEach((file) => console.log(readFileSync(file, 'utf8')));
+// 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
+  .create('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.
+
+### Async Transforms
+
+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(),
+      },
+    };
+  },
+);
 ```
 
 ## Epilog
@@ -405,16 +422,12 @@ By default, **bargs** displays your package's homepage and repository URLs (from
 
 ```typescript
 // Custom epilog
-bargs({
-  name: 'my-cli',
+bargs.create('my-cli', {
   epilog: 'For more info, visit https://example.com',
 });
 
 // Disable epilog entirely
-bargs({
-  name: 'my-cli',
-  epilog: false,
-});
+bargs.create('my-cli', { epilog: false });
 ```
 
 ## Theming
@@ -423,38 +436,23 @@ Customize help output colors with built-in themes or your own:
 
 ```typescript
 // Use a built-in theme: 'default', 'mono', 'ocean', 'warm'
-bargs(
-  {
-    name: 'my-cli',
-    options: { verbose: bargs.boolean() },
-  },
-  { theme: 'ocean' },
-);
+bargs.create('my-cli', { theme: 'ocean' });
 
 // Disable colors entirely
-bargs(config, { theme: 'mono' });
+bargs.create('my-cli', { theme: 'mono' });
 ```
 
-The `ansi` export provides common ANSI escape codes for styled terminal output: text styles (`bold`, `dim`, `italic`, `underline`, etc.), foreground colors, background colors, and their `bright*` variants. Use this to create your own themes (instead of hardcoding ANSI escape codes).
+The `ansi` export provides common ANSI escape codes for styled terminal output:
 
 ```typescript
 import { ansi } from '@boneskull/bargs';
 
-bargs(someConfig, {
+bargs.create('my-cli', {
   theme: {
     command: ansi.bold,
-    defaultText: ansi.dim,
-    defaultValue: ansi.white,
-    description: ansi.white,
-    epilog: ansi.dim,
-    example: ansi.white + ansi.dim,
     flag: ansi.brightCyan,
     positional: ansi.magenta,
-    scriptName: ansi.bold,
-    sectionHeader: ansi.brightMagenta,
-    type: ansi.magenta,
-    url: ansi.cyan,
-    usage: ansi.cyan,
+    // ...
   },
 });
 ```
@@ -495,14 +493,16 @@ import {
 } from '@boneskull/bargs';
 
 try {
-  bargs(config);
+  await bargs.create('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) {
-    // User needs guidance (e.g., unknown option)
-    console.error(error.message);
+    // 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);
@@ -512,11 +512,12 @@ try {
 
 ### Programmatic Help
 
-Generate help text without calling `bargs()`:
+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');
 ```
@@ -558,11 +559,16 @@ console.log(styler.flag('--verbose'));
 
 // Strip ANSI codes for plain text output
 const plain = stripAnsi('\x1b[32m--verbose\x1b[0m'); // '--verbose'
-
-// Override some colors in a built-in theme
-const customTheme = { ...themes.ocean, colors: { flag: ansi.green } };
 ```
 
+### Low-Level Utilities
+
+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 v22+.
+
 ## Motivation
 
 I've always reached for [yargs](https://github.com/yargs/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.