# Overview

> burgee serves one command declaration as help, --json, --schema, an MCP server, completions and types; answers an agent with exit codes, fix: lines and --explain; takes no dependency outside its family; and grades each drop-in path by the incumbent's own test suite.

Source: https://burgee.interlace.tools/docs

**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.

```text
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 on

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](/docs/agent-surfaces) has each surface, and
[What an agent sees](/docs/what-an-agent-sees) has recorded sessions of a model using them.

## One supply chain

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](/docs/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](/docs/supply-chain).

## Proved by each incumbent's own suite

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](/docs/compatibility), generated, never hand-edited.
The [benchmarks](/docs/benchmarks) publish every comparison, the rows burgee loses included.

## Start in one command

```bash
npx burgee init my-cli && cd my-cli && npm install
```

It writes `cli.mjs` and a `package.json`, and nothing else.
[Getting started](/docs/getting-started) goes on from there.

## Switch in one command

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

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

[Migrate](/docs/migrate) has the whole report, and [Switching from commander](/docs/vs/commander)
and [Switching from yargs](/docs/vs/yargs) go through each API.

## Where to go next

- [Getting started](/docs/getting-started) — one file, one command, and an agent connected
  to it while you write it.
- [Why it's built this way](/docs/why) — the five choices behind the family, what each one
  gives you, and what it does not claim.
- [Concepts](/docs/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](/docs/packages) — the ten packages of the family, each with no dependency
  outside it, each with its own incumbents and its own site.
- [Compatibility](/docs/compatibility) — every host suite, every pass rate, generated.
- [Your CLI is an agent tool](/docs/agent-surfaces) — `--schema`, `--mcp`, completions and
  `--explain`.
- [The floor](/docs/the-floor) — the requirements every CLI on burgee meets.

For agents: [`/llms.txt`](/llms.txt) is the map, [`/llms-full.txt`](/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](https://github.com/ofri-peretz/burgee/tree/main/.sdlc/research).