burgee vs yargs

burgee is a yargs alternative you adopt by changing one import. burgee/yargs implements yargs' API itself — the factory, the instance, the helpers — and yargs' own test suite is the grade.

Migrate from yargs in one import

- import yargs from 'yargs';
- import { hideBin } from 'yargs/helpers';
+ import yargs from 'burgee/yargs';
+ import { hideBin } from 'burgee/yargs/helpers';

Your program and your tests stay as they are. npx burgee migrate --dry-run rewrites yargs, yargs/yargs and yargs/helpers across a codebase, prints the plan first, and refuses — by file and line — anything it cannot rewrite mechanically.

Is it really compatible with yargs?

Compatibility is graded, not claimed. yargs' own test suite — vendored, unmodified apart from the import specifier — runs against burgee/yargs in CI, beside a control that runs the same suite against real yargs:

From Compatibility, which npm run compat:page generates from the oracle's last run; this table is copied from it and that page is the authority. Rates are measured against the control's total, so a file that fails to import cannot flatter the number.

What you gain over yargs

• --json — every command's result in one stable envelope, { "ok": true, "data": … }, with errors in the same shape.
• --schema — the command tree as data, with a JSON Schema per command; no handler runs, so an agent can call it first.
• --mcp — the same commands as MCP tools over stdio, exposed only when a command declares its effects.
• Completions — completion bash | zsh | fish | pwsh, static scripts generated from the declaration.
• An exit-code contract — 2 means rewrite the command; any other non-zero means the command was fine and the world was not.

yargs offers middleware on one program; a burgee plugin is written once and shared across programs, and works on yargs syntax, commander syntax and native alike.

Weight against yargs

From the root README's Measured table (2026-09-09, one machine, generated by npm run bench — see Benchmarks):

The lighter-than-yargs gate — burgee/yargs lighter in a bundle than yargs — is met (0.947×). Installed size is larger, and stays on the page.

When to switch

• You want your CLI usable by an AI agent without writing tool definitions by hand.
• You want fewer packages in your install tree: yargs brings six runtime dependencies, burgee none outside the burgee family.
• You want --json, --schema and completions from the definition you already wrote.