Overview

burgee is a CLI framework built on one declaration. You declare a command once, and help, --json, --schema, an MCP server, shell completions and TypeScript types are all read from that declaration, so none of them can drift from the others.

defineCommand()  ──▶  manifest  ──┬──▶  human help
                                  ├──▶  --json      one stable envelope
                                  ├──▶  --schema    versioned, one document per surface
                                  ├──▶  --mcp       an MCP server, generated
                                  ├──▶  completions bash · zsh · fish · pwsh
                                  ├──▶  TypeScript types
                                  └──▶  docs + llms.txt

Contracts an agent can act onCopy Anchor Link

An agent calling a CLI through a shell pays in calls, tokens and misreads. A burgee command gives it contracts instead of prose to interpret:

• a stable { ok, data } envelope under --json, and a versioned schema under --schema;
• an exit code that says rewrite the command (2) rather than something went wrong;
• a fix: line on a mistyped command, which the agent can run as written;
• --explain <option>, which says whether a value came from a flag, an environment variable, a config file or a default;
• the same commands as MCP tools under --mcp.

Your CLI is an agent tool has each surface, and What an agent sees has recorded sessions of a model using them.

One supply chainCopy Anchor Link

Ten packages, one repository, one release pipeline, and no dependency outside the burgee family in any of them. Six take nothing at all; the other four take only each other. Packages has each one. Every release is published with npm provenance and no npm token, and what installing each package brings in is listed on Supply chain and continuity.

Proved by each incumbent's own suiteCopy Anchor Link

Every drop-in path is graded by the original package's own test suite, vendored unmodified apart from the import specifier and run in CI beside a control that runs the real package. The rates are on Compatibility, generated, never hand-edited. The benchmarks publish every comparison, the rows burgee loses included.

Switch in one commandCopy Anchor Link

npx burgee migrate --dry-run
npx burgee migrate

burgee has drop-in paths for commander and yargs, and the family has them for chalk, ora, string-width and the other packages graded level with their own suites. burgee migrate rewrites the import specifiers and nothing else, then prints the install command to run next. For one commander program, that is one line:

- import { Command } from 'commander';
+ import { Command } from 'burgee/commander';

Migrate has the whole report, and Switching from commander and Switching from yargs go through each API.

Where to go nextCopy Anchor Link

• Getting started — one file, one command, and an agent connected to it while you write it.
• Why it's built this way — the five choices behind the family, what each one gives you, and what it does not claim.
• Concepts — how the family works on its own terms: the layers, the output policy, plugins, exit codes, shutdown, configuration, and how each claim is proven.
• Packages — the ten packages of the family, each with no dependency outside it, each with its own incumbents and its own site.
• Compatibility — every host suite, every pass rate, generated.
• Your CLI is an agent tool — --schema, --mcp, completions and --explain.
• The floor — the requirements every CLI on burgee meets.

For agents: /llms.txt is the map, /llms-full.txt the whole corpus, and every page has a Markdown twin at its own URL plus .md. The source and the research behind every claim are on GitHub.