# burgee vs yargs

> A yargs alternative that is drop-in compatible: change one import, keep your code and tests, and gain --json, --schema, --mcp and shell completions — with no dependency outside the burgee family where yargs has six.

Source: https://burgee.interlace.tools/docs/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

```diff
- 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:

| | passing | rate |
| :-- | --: | --: |
| `burgee/yargs` | 804 / 804 | 100.0% |
| yargs itself (control) | 802 / 804 | 99.8% |

From [Compatibility](/docs/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](/docs/plugins) 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](/docs/benchmarks)):

| | burgee | yargs |
| :-- | --: | --: |
| Runtime dependencies | 5, none outside the burgee family | 6 |
| Full CLI run over bare node | +14.0 ms | +78.5 ms |
| Installed size | 1154 KB | 515 KB |

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.