CLI

New scripts parse arguments with commander through @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

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 both forward git diff --stat.
• Bun drops a -- that comes first after the script path, so ./tool.ts -- git --stat reaches commander as git --stat. passThroughOptions() forwards both spellings the same way.
• passThroughOptions() requires enablePositionalOptions() on every ancestor, and throws at parse time when one lacks it.

Testing

Call exitOverride() and configureOutput() on every command in the tree. addCommand does not copy them to children. With both set, a parse error or --help throws a CommanderError carrying code and exitCode instead of exiting, and output lands in the test.

import { CommanderError, type CommandUnknownOpts } from "@commander-js/extra-typings";
import { expect, test } from "bun:test";
import { program, start } from "./trials";

async function run(command: CommandUnknownOpts, argv: string[]): Promise<string> {
  let output = "";
  const configure = (cmd: CommandUnknownOpts): void => {
    cmd.exitOverride().configureOutput({
      writeOut: (text) => {
        output += text;
      },
      writeErr: (text) => {
        output += text;
      },
    });
    for (const sub of cmd.commands) configure(sub);
  };
  configure(command);
  await command.parseAsync(argv, { from: "user" });
  return output;
}

test("forwards the command after the leaf's options", async () => {
  await run(program, ["trial", "start", "--name", "x", "--", "git", "diff"]);
  expect(start.opts().name).toBe("x");
  expect(start.processedArgs).toEqual([["git", "diff"]]);
});

test.each<{ name: string; argv: string[]; code: string; exitCode: number }>([
  { name: "unknown subcommand", argv: ["trial", "nope"], code: "commander.unknownCommand", exitCode: 1 },
  { name: "help", argv: ["--help"], code: "commander.helpDisplayed", exitCode: 0 },
])("$name exits through CommanderError", async ({ argv, code, exitCode }) => {
  const failure = await run(program, argv).catch((error: unknown) => error);
  expect(failure).toBeInstanceOf(CommanderError);
  expect(failure).toMatchObject({ code, exitCode });
});

• Pass { from: "user" } so commander reads argv as arguments only, with no runtime and script path in front.
• parseAsync resolves to the command, not the action's return value. Assert on a leaf's typed opts() and processedArgs, or on the exported core functions the action calls.
• Reparsing the same program is safe. Commander restores option defaults before each parse.

Conventions

• Shebang: #!/usr/bin/env bun
• Entry point: call await program.parseAsync() inside if (import.meta.main) so the module is importable.
• Export the root program, any leaf a test inspects, and the core functions. Keep argument parsing in the command definitions.
• A distributed plugin declares both commander and @commander-js/extra-typings in its own package.json at the same ~15.0.0 range, then regenerates its lockfile with bun run plugin-lockfiles generate. extra-typings pins its commander peer to one minor line, so the two upgrade together. Renovate groups them into one PR.