/cli

name: cli
description: Type-safe CLI argument parsing with commander and @commander-js/extra-typings, the standard parser for this repo's Bun scripts. Use when writing or editing any script that takes arguments (flags, positional parameters, subcommands, nested subcommands, --help) instead of reading existing scripts for the pattern.

CLI

New scripts parse arguments with [commander](https://github.com/tj/commander.js) through [`@commander-js/extra-typings`](https://github.com/commander-js/extra-typings), which infers each option's and argument's type from its flag string. Scripts still on cleye migrate to commander over time.

Import `Command`, `Option`, and the error classes from `@commander-js/extra-typings`. Importing them from `commander` drops the inference and types every option as `any`.

Basic Usage

#!/usr/bin/env bun

import { Command, Option } from "@commander-js/extra-typings";

export const program = new Command("scan")
  .description("Scan repository prose for AI writing tropes.")
  .argument("<path>", "directory to scan")
  .option("-o, --output <file>", "output path")
  .addOption(new Option("--format <format>", "output format").choices(["text", "json"]).default("text"))
  .option("--dry-run", "report without writing")
  .action((path, options) => {
    console.log(path); // string
    console.log(options.output); // string | undefined
    console.log(options.format); // "text" | "json"
    console.log(options.dryRun); // true | undefined
  });

if (import.meta.main) {
  await program.parseAsync();
}

The action receives each declared argument in order, then the options object, then the command. Reading an undeclared key such as `options.outptu` is a type error.

`parseAsync` handles `--help` and `-h`, and awaits an async action. A missing argument, an unknown option, an excess positional, or a value outside `choices` prints an error and exits 1.

Options

| Declaration | Type | | --- | --- | | `--name <value>` | `string \| undefined` | | `--flag` | `true \| undefined` | | `--no-color` | `boolean`, default `true` | | `--since [date]` | `string \| true \| undefined` | | `.requiredOption("--repo <r>")` | `string` | | `.option("--limit <n>", "…", int, 20)` | `number` | | `.argument("<path>")` | `string` | | `.argument("[files...]")` | `string[]` |

A default or `requiredOption` drops `undefined` from the type. A kebab-case flag (`--dry-run`) arrives as a camelCase key (`dryRun`). An enum needs `addOption` with `new Option(...).choices([...])`, which types the value as the union.

Numbers and Repeated Flags

Commander has no number type and keeps only the last value of a repeated flag. Pass a parser function as the third argument for both:

#!/usr/bin/env bun

import { Command, InvalidArgumentError } from "@commander-js/extra-typings";

function int(value: string): number {
  const n = Number(value);
  if (!Number.isInteger(n)) throw new InvalidArgumentError("Not an integer.");
  return n;
}

function collect(value: string, previous: string[] = []): string[] {
  return [...previous, value];
}

export const program = new Command("search")
  .option("-n, --limit <n>", "maximum results", int, 20)
  .option("--tag <name>", "tag to match, repeatable", collect, [])
  .requiredOption("--label <name>", "label to apply, repeatable", collect)
  .action((options) => {
    console.log(options.limit); // number
    console.log(options.tag); // string[]
    console.log(options.label); // string[]
  });

if (import.meta.main) {
  await program.parseAsync();
}

• Copy `int` and `collect` into each script that uses them. A distributed plugin cannot import them from another plugin or a workspace package, and they are too small to publish.
• A required repeated flag takes `collect` with no default. `requiredOption` counts a `[]` default as present and never reports the flag missing.
• An `InvalidArgumentError` thrown from a parser prints `error: option '...' argument '...' is invalid. <message>` and exits 1.
• Use `collect` for repeated flags instead of a variadic option (`--tag <names...>`), which also absorbs every positional that follows it.

Subcommands

Build each command with `new Command(name)` and attach it with `addCommand`. A group is a command whose children are its actions, so `trials trial start` nests with no extra wiring:

#!/usr/bin/env bun

import { Command } from "@commander-js/extra-typings";

export const start = new Command("start")
  .description("Start a trial.")
  .option("--name <name>", "trial name", "trial")
  .argument("<command...>", "command to run, with its arguments")
  .passThroughOptions()
  .action((forward, options) => {
    console.log(options.name, forward);
  });

const end = new Command("end").description("End a trial.").action(() => {
  console.log("ended");
});

const trial = new Command("trial")
  .description("Start or end a trial.")
  .enablePositionalOptions()
  .addCommand(start)
  .addCommand(end);

export const program = new Command("trials").enablePositionalOptions().addCommand(trial);

if (import.meta.main) {
  await program.parseAsync();
}

• A group without an action prints its usage and exits 1 when invoked without a subcommand.
• Options declared on a group belong to the group, and must precede the subcommand under `enablePositionalOptions()`. A leaf reads them with `command.optsWithGlobals()`, which types them only when the group's `.command(name)` created the leaf. A leaf attached with `addCommand` gets them at runtime without the types.
• `--` does not reach the action as its own value. `[forward...]` holds the operands before `--` and after it with no boundary between them, so a stray positional before `--` gets forwarded.
• To forward arguments to another program, declare `<command...>` and call `passThroughOptions()` on the leaf. Everything from the first positional onward forwards verbatim, including flags, so `start --name x git diff --stat` and `start --name x -- git diff --stat