Skip to content
Back to search

burgee

Everything a CLI needs that isn't your CLI: one declaration gives help, --json, --schema, MCP and completions. Drop-in for commander, yargs and meow. An Interlace project.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ofri-peretz/burgee with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ofri-peretz/burgee'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ofri-peretz--burgee/badge.svg)](/listings/ofri-peretz--burgee)

HTML

<a href="/listings/ofri-peretz--burgee"><img src="/api/listings/ofri-peretz--burgee/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 712 lines
  1. <p align="center">
  2. <a href="https://www.npmjs.com/package/burgee" target="blank">
  3. <picture>
  4. <source media="(prefers-color-scheme: dark)" srcset="./brand-assets/burgee-lockup.svg" />
  5. <img src="./brand-assets/burgee-lockup-light.svg" alt="burgee" width="360" />
  6. </picture>
  7. </a>
  8. </p>
  9. <p align="center">
  10. Everything a CLI needs that isn't your CLI. Written once, served to humans and agents alike.
  11. </p>
  12. <p align="center">
  13. <a href="https://www.npmjs.com/package/burgee"><img src="https://img.shields.io/npm/v/burgee?style=flat-square&color=0a6b47" alt="npm version" /></a>
  14. <a href="https://www.npmjs.com/package/burgee"><img src="https://img.shields.io/npm/dm/burgee?style=flat-square" alt="npm downloads" /></a>
  15. <a href="https://github.com/ofri-peretz/burgee/actions/workflows/quality.yml"><img src="https://github.com/ofri-peretz/burgee/actions/workflows/quality.yml/badge.svg?branch=main" alt="Quality Gate" /></a>
  16. <a href="https://github.com/ofri-peretz/burgee/actions/workflows/codeql.yml"><img src="https://github.com/ofri-peretz/burgee/actions/workflows/codeql.yml/badge.svg?branch=main" alt="CodeQL" /></a>
  17. <a href="https://app.codecov.io/gh/ofri-peretz/burgee"><img src="https://codecov.io/gh/ofri-peretz/burgee/branch/main/graph/badge.svg" alt="Coverage" /></a>
  18. <a href="https://scorecard.dev/viewer/?uri=github.com/ofri-peretz/burgee"><img src="https://api.scorecard.dev/projects/github.com/ofri-peretz/burgee/badge" alt="OpenSSF Scorecard" /></a>
  19. <a href="./packages/burgee/package.json"><img src="https://img.shields.io/badge/dependencies-5%20in%20family%2C%200%20outside-0a6b47?style=flat-square" alt="Five dependencies, all in the burgee family: no dependency outside the burgee family" /></a>
  20. <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22.13%2B-green.svg?style=flat-square" alt="Node.js 22.13+" /></a>
  21. <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.9+-blue.svg?style=flat-square" alt="TypeScript" /></a>
  22. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT" /></a>
  23. <a href="https://github.com/ofri-peretz/burgee"><img src="https://img.shields.io/github/stars/ofri-peretz/burgee?style=flat&logo=github&label=Star" alt="GitHub stars" /></a>
  24. </p>
  25. Declare a command once. burgee serves it as help for a person, `--json` for a script and an
  26. MCP server for an agent.
  27. ```bash
  28. npm i burgee
  29. ```
  30. Before, with commander:
  31. ```js
  32. // cli.mjs
  33. import { Command } from 'commander';
  34. new Command('greet')
  35. .description('Greet someone by name')
  36. .requiredOption('--name <name>', 'who to greet')
  37. .action(({ name }) => console.log(`hello, ${name}`))
  38. .parse();
  39. ```
  40. After, with burgee. The command is a declaration, and the same file now answers a script and
  41. an agent too:
  42. ```js
  43. // cli.mjs
  44. import { defineCommand, run } from 'burgee';
  45. run(defineCommand({
  46. name: 'greet',
  47. description: 'Greet someone by name',
  48. options: { name: { type: 'string', required: true, description: 'who to greet' } },
  49. effects: 'read_only', // it changes nothing, and --mcp tells the agent so
  50. run: ({ options }) => ({ greeting: `hello, ${options.name}` }),
  51. }));
  52. ```
  53. ```console
  54. $ node cli.mjs --name ada
  55. greeting: hello, ada
  56. $ node cli.mjs --name ada --json
  57. {"ok":true,"data":{"greeting":"hello, ada"},"meta":{"provenance":{"name":{"source":"flag","location":"--name"}}}}
  58. $ node cli.mjs --mcp --print-config # paste into an MCP client; the path is yours
  59. {
  60. "mcpServers": {
  61. "greet": {
  62. "command": "node",
  63. "args": [
  64. "/path/to/cli.mjs",
  65. "--mcp"
  66. ]
  67. }
  68. }
  69. }
  70. $ node cli.mjs --help
  71. Usage: greet <command> [options]
  72. Greet someone by name
  73. Options:
  74. --name <value> who to greet (required)
  75. Global options:
  76. --json machine-readable output
  77. --help show this help
  78. --schema the program as data
  79. --color <when> always, never or auto (default: auto); NO_COLOR is honoured
  80. --no-color the same as --color=never
  81. -q, --quiet silence progress and hints; data and errors still print
  82. --timeout <duration> end the run after this long, exit 6: 500ms, 5s, 2m
  83. --explain <option> where an option's value came from
  84. Commands:
  85. completion <shell> Print a shell completion script: bash, zsh, fish, pwsh or fig
  86. Exit codes:
  87. 0 ok: the command completed
  88. 1 runtime: it ran and failed; read the message
  89. 2 usage: bad arguments or an unknown command; rewrite the command
  90. 3 config: the config or environment did not load; fix it, not the command
  91. 4 cancelled: cancelled, or a decision is needed; decide, then run a next
  92. command
  93. 6 timeout: the --timeout deadline passed; run it again with more time
  94. 130 sigint: interrupted; stop
  95. For agents: --schema prints every command, option, default and env var as JSON, in one call. --json
  96. prints one envelope on stdout, and --explain <option> says where a value came from.
  97. ```
  98. <p align="center">
  99. <strong>📖 Docs: <a href="https://burgee.interlace.tools">burgee.interlace.tools</a></strong>
  100. &nbsp;·&nbsp; <a href="https://burgee.interlace.tools/llms.txt">llms.txt</a>
  101. </p>
  102. <p align="center">
  103. <a href="#-start-here">Start here</a> &nbsp;·&nbsp;
  104. <a href="#-switch-in-one-command">Switch in one command</a> &nbsp;·&nbsp;
  105. <a href="#-measured">Measured</a> &nbsp;·&nbsp;
  106. <a href="#-the-family">The family</a> &nbsp;·&nbsp;
  107. <a href="#-status">Status</a> &nbsp;·&nbsp;
  108. <a href="#-repo-map">Repo map</a> &nbsp;·&nbsp;
  109. <a href="./.sdlc/research/">Research</a>
  110. </p>
  111. <p align="center">
  112. <strong>One declaration, six surfaces.</strong> Declare a command once and burgee serves it as
  113. help, a --json envelope, a versioned --schema, an MCP server, shell completions and TypeScript
  114. types. Nothing is written twice, so no surface can drift from another.
  115. </p>
  116. <p align="center">
  117. <strong>Contracts an agent can act on.</strong> Exit code 2 means <em>rewrite the command</em>;
  118. any other failure means the command was right and the world was not. A mistyped command comes
  119. back with a <em>fix:</em> line the agent can run as written, and --explain says which flag,
  120. environment variable, config file or default each value came from.
  121. </p>
  122. <p align="center">
  123. <strong>One supply chain.</strong>
  124. Eleven packages, one repository, one release pipeline, and no dependency outside the burgee
  125. family in any of them. Six take nothing at all; the other four take only each other.
  126. </p>
  127. <p align="center">
  128. <strong>Proved by the incumbents' own tests.</strong> Each drop-in path is graded by the
  129. original package's own test suite, run in CI beside a control that runs the real package:
  130. commander's 1418 of 1418, yargs' 816 of 816, and 38 more hosts on the compatibility page.
  131. The benchmarks below publish every comparison, the rows burgee loses included.
  132. </p>
  133. <p align="center">
  134. <strong>⭐ <a href="https://github.com/ofri-peretz/burgee">Star the repo</a></strong> &nbsp;·&nbsp;
  135. <a href="https://github.com/ofri-peretz/burgee/subscription">👀 Watch releases</a> &nbsp;·&nbsp;
  136. <a href="https://github.com/ofri-peretz/burgee/issues">🐛 Report a bug</a>
  137. </p>
  138. ---
  139. ## 👋 Start here
  140. ```bash
  141. npx burgee init my-cli && cd my-cli && npm install
  142. ```
  143. `init` writes this file as `cli.mjs`, and a `package.json` that runs it. Nothing else.
  144. ```js
  145. #!/usr/bin/env node
  146. // cli.mjs — the whole CLI
  147. import { defineCommand, run } from 'burgee';
  148. run(defineCommand({
  149. name: 'greet',
  150. description: 'Greet someone by name',
  151. options: { name: { type: 'string', required: true, description: 'who to greet' } },
  152. effects: 'read_only', // what running it does to the world; required, and what --mcp reads
  153. run: ({ options }) => ({ greeting: `hello, ${options.name}` }),
  154. }));
  155. ```
  156. ```console
  157. $ node cli.mjs --name ada
  158. greeting: hello, ada
  159. $ node cli.mjs --name ada --json
  160. {"ok":true,"data":{"greeting":"hello, ada"},"meta":{"provenance":{"name":{"source":"flag","location":"--name"}}}}
  161. $ node cli.mjs # exit 2, not 1
  162. error: missing required option --name
  163. hint: pass --name <value>
  164. usage: greet [options]
  165. options:
  166. --name <value> who to greet (required)
  167. ```
  168. That is the whole thing: one file, one declaration, and a CLI that already speaks to a person,
  169. to a script and to an agent.
  170. > A **burgee** is the small swallowtail flag a boat flies to say which club it belongs to — a
  171. > flag of identity, not of instruction. That is what a command does here: declares itself
  172. > once, and every surface is that declaration read by a different reader.
  173. ---
  174. ## 🎏 One declaration, every surface
  175. ```text
  176. defineCommand() ──▶ manifest ──┬──▶ human help
  177. ├──▶ --json one stable envelope
  178. ├──▶ --schema versioned, one document per surface
  179. ├──▶ --mcp an MCP server, generated
  180. ├──▶ completions bash · zsh · fish · pwsh
  181. ├──▶ TypeScript types
  182. └──▶ docs + llms.txt
  183. ```
  184. Surfaces cannot drift, because there is nothing to keep in sync. Adding the next one is an
  185. emitter, not a feature.
  186. ---
  187. ## 🤖 What an agent sees
  188. The same command, asked for its own definition. No wrapper, no sidecar file, no scraping
  189. `--help`:
  190. ```console
  191. $ node cli.mjs --schema # trimmed; arguments and examples also come back
  192. {
  193. "options": {
  194. "name": { "type": "string", "required": true, "description": "who to greet" }
  195. },
  196. "inputSchema": { "type": "object", "properties": { "name": { "type": "string" } } }
  197. }
  198. $ node cli.mjs --mcp # the same command, served as an MCP server over stdio
  199. ```
  200. Every `--schema` document validates against `burgee/program-schema.json`, the JSON Schema the
  201. package publishes, so a project can pin its CLI's surface in CI without writing its own idea of
  202. the shape.
  203. Six issues in the yargs tracker, all still open and filed between 2017 and 2022, ask to list
  204. or introspect commands from code, and the state of the art today is a regex over `--help`
  205. ([tracker-gap-analysis.md](./.sdlc/research/tracker-gap-analysis.md)). A manifest is not a
  206. feature bolted on for agents — it is the thing help was rendered from in the first place.
  207. What that is worth needs no model to measure. Ten tasks per variant, one spawn each,
  208. non-TTY with **stdin closed** — the only environment an agent gets — running the same demo
  209. program on each engine:
  210. | Variant | hangs / 100 | exit code correct | `--json` answered |
  211. | :--- | ---: | ---: | ---: |
  212. | **burgee** | 0 | **100.0%** | **100.0%** |
  213. | commander | 0 | 40.0% | 25.0% |
  214. | yargs | 0 | 40.0% | 25.0% |
  215. Exit code is the one that decides an agent's next move: `2` means *rewrite the command*, any
  216. other non-zero means *the command was fine and the world was not*. This measures legibility,
  217. not tokens. The token and turn halves of B1 run a model against the same program on every push
  218. to `main`. [What an agent sees](https://burgee.interlace.tools/docs/what-an-agent-sees) quotes
  219. those sessions and lists every run, including the ones where the claim in [Measured](#-measured)
  220. misses.
  221. ---
  222. ## 🔌 Extend every layer
  223. Every released package in the family takes plugins, and all nine take them the same way. A plugin is a
  224. plain object. Each package validates it against **one published schema** — the same
  225. `schema.json` ships in every package — and each has a `check` command that shows what a plugin
  226. contributes, or refuses it with a code and the fix, before it ships.
  227. Each package reads its own key and ignores the rest, so **one object can extend every layer at
  228. once**: brand colours, a spinner, a terminal quirk, a config source, where the company's tools
  229. live, what to flush on exit, a prompt of its own, and a command every one of its CLIs gets.
  230. <!-- plugins:start -->
  231. | Package | A plugin adds | Check it |
  232. | :--- | :--- | :--- |
  233. | [`bellpull`](./packages/bellpull/) | `resolvers` | `npx bellpull check ./plugin.mjs` |
  234. | [`burgee`](./packages/burgee/) | `commands`, `hooks`, `locales`, `formats` | `npx burgee check ./plugin.mjs` |
  235. | [`caique`](./packages/caique/) | `widgets`, `locales` | `npx caique check ./plugin.mjs` |
  236. | [`closeout`](./packages/closeout/) | `handlers` | `npx closeout check ./plugin.mjs` |
  237. | [`controlroom`](./packages/controlroom/) | `keymaps`, `panes` | `npx controlroom check ./plugin.mjs` |
  238. | [`flagstaff`](./packages/flagstaff/) | `tokens`, `glyphs`, `spinners`, `borders`, `components` | `npx flagstaff check ./plugin.mjs` |
  239. | [`linegauge`](./packages/linegauge/) | `widths` | `npx linegauge check ./plugin.mjs` |
  240. | [`paratext`](./packages/paratext/) | `capabilities` | `npx paratext check ./plugin.mjs` |
  241. | [`roundel`](./packages/roundel/) | `tokens` | `npx roundel check ./plugin.mjs` |
  242. | [`seniority`](./packages/seniority/) | `sources` | `npx seniority check ./plugin.mjs` |
  243. <!-- plugins:end -->
  244. Where an incumbent has an extension point — commander's `.hook()`, yargs middleware,
  245. cosmiconfig's loaders, inquirer's `createPrompt` — it lives in one program or one call. A
  246. plugin here is written once and shared: across programs, across layers, and across commander,
  247. yargs and native syntax alike. The [plugins page](./apps/docs/content/docs/plugins.mdx) has the
  248. whole nine-layer example, which every released package's `check` accepts in CI, each incumbent's own
  249. extension point beside ours, and what a plugin cannot do yet.
  250. ---
  251. ## 🔁 Switch in one command
  252. ```bash
  253. npx burgee migrate --dry-run # what it would change, and nothing written
  254. npx burgee migrate
  255. ```
  256. burgee has **drop-in paths for commander and yargs**, and the family has them for chalk, ora,
  257. string-width, cross-spawn, signal-exit and the other packages graded level with their own
  258. suites. `burgee migrate` rewrites the import specifiers and nothing else, then
  259. prints the install command to run next ([Migrate](./apps/docs/content/docs/migrate.mdx)). For
  260. one commander program, that is one line:
  261. ```diff
  262. - import { Command } from 'commander';
  263. + import { Command } from 'burgee/commander';
  264. ```
  265. Your code and your tests are unchanged. Compatibility is not asserted here, it is graded —
  266. each host's own suite, vendored unmodified apart from the import specifier, pointed at
  267. burgee and run in CI against a control that runs the real host:
  268. | Host | Front-end | burgee | rate |
  269. | :-- | :-- | ---: | ---: |
  270. | commander | `burgee/commander` | 1418 / 1418 | **100%** |
  271. | yargs | `burgee/yargs` | 816 / 816 | **100%** |
  272. Measured 2026-09-09 (yargs 2026-09-30, at 18.2.0); 38 more hosts are in
  273. the [full table](./apps/docs/content/docs/compatibility.mdx), generated by
  274. `npm run compat:page` and never hand-edited. Rates are measured against the control's total
  275. rather than against registered tests, because a file that fails to import registers as one
  276. test instead of its twenty and would flatter a partial implementation.
  277. What changes after the switch is what the program can do. It answers `--json`, `--schema` and
  278. `--mcp`, and it takes **plugins**. commander has no plugin API: its RFC
  279. ([#2505](https://github.com/tj/commander.js/issues/2505)) was closed for inactivity on
  280. 2026-10-09 without one. yargs offers middleware on one program, not a plugin shared across
  281. programs. A plugin contributes to
  282. the manifest, and the manifest never records which façade filled it, so one plugin works on
  283. commander syntax, yargs syntax and native alike.
  284. ---
  285. ## 🧭 It starts as one file
  286. oclif has every capability on this page and does **10.9M downloads a week against
  287. commander's 508M**. The difference is not features, it is shape. So the shape is locked
  288. first, ahead of every other requirement, and `Z1` is a **test**: it installs the published
  289. tarball into a temp directory, writes exactly one file, and runs it. The day that needs a
  290. second file, a config or a build step, CI goes red.
  291. Everything beyond that first rung — precomputed manifests, plugins, the dev loop, scaffolding
  292. — is additive and removable.
  293. ---
  294. ## 📏 Measured
  295. 2026-10-08 (`ba8a89c`), a GitHub Actions runner (AMD EPYC 7763, 4 cores), linux/x64, Node 24, 52 interleaved spawns per variant. † is a
  296. published figure taken on another machine, not reproduced here ([measured](https://burgee.interlace.tools/docs/benchmarks)).
  297. | | **burgee** | commander | yargs | @oclif/core | cac |
  298. | :--- | ---: | ---: | ---: | ---: | ---: |
  299. | Runtime dependencies | **5**, none outside the burgee family | 0 | 6 | **18** | 0 |
  300. | Full CLI run over bare node | +20.3 ms | +14.8 ms | +75.0 ms | +131 ms † | +3.8 ms |
  301. | Installed size | 1690 KB | 203 KB | 515 KB | 912 KB † | 40 KB |
  302. The speed comes from `node:util.parseArgs` being in the standard library, not from a faster
  303. language: burgee is TypeScript, like both incumbents.
  304. Milliseconds are a property of the machine that produced them, so nothing gates on them.
  305. What is gated is the ratio between two spawns interleaved in the same run, which cancels the
  306. machine out. Ten of those gates are stated in public — **all ten are met, three of them as
  307. downward-only ratchets rather than the bar they started with, and the two agent claims as the
  308. median of a named window of CI runs rather than any one run** ([measured](https://burgee.interlace.tools/docs/benchmarks)):
  309. | Claim | Gate | Measured | |
  310. | :--- | :--- | ---: | :--- |
  311. | the core entry point is under 52 KB bundled | `core-under-52kb-bundled` | 24,528 bytes | ✅ met |
  312. | `burgee/yargs` is lighter in a user's bundle than `yargs` | `lighter-than-yargs` | 0.986× | ✅ met |
  313. | `burgee` is lighter than `cac` **plus what a cac user installs to match it** | `lighter-than-cac-at-parity` | 0.249× | ✅ met |
  314. | `burgee/commander` is lighter than `commander` **plus the same** | `lighter-than-commander-at-parity` | 0.436× | ✅ met |
  315. | `burgee/yargs` is lighter than `yargs` **plus the same** | `lighter-than-yargs-at-parity` | 0.553× | ✅ met |
  316. | `burgee` starts within 1.55× of `cac`, the lightest framework in the landscape (ratchet; lowered as it speeds up) | `cold-start-at-or-below-cac` | 1.443× | ✅ met |
  317. | `burgee/commander` stays within 1.42× of `commander` alone in a user's bundle (ratchet; lowered as it shrinks) | `lighter-than-commander` | 1.416× | ✅ met |
  318. | `burgee` stays within 2.35× of `cac` alone in a user's bundle (ratchet; lowered as it shrinks) | `lighter-than-cac` | 2.347× | ✅ met |
  319. | an agent spends ≥40% fewer tokens over the benchmark tasks (total over every task-run) | `agent-tokens-40pct` | median 0.502× over the 52 CI readings dated 2026-10-10 to 2026-10-18 (range 0.434–0.627), at or under 0.6 in 51 of them | ✅ met |
  320. | an agent takes ≥30% fewer turns over the benchmark tasks (total over every task-run) | `agent-turns-30pct` | median 0.522× over the 52 CI readings dated 2026-10-10 to 2026-10-18 (range 0.446–0.634), at or under 0.7 in 52 of them | ✅ met |
  321. **The two agent claims changed measure on 2026-10-09** (D-20261009-b1-totals-and-explain). They
  322. compared pooled medians until then, and the median ratio was decided by commander's luck: burgee
  323. holds at 3 turns, while commander's median lands at 4 or 6 from run to run, so the same build
  324. read 0.5 or 0.75. They now compare the tokens and turns each CLI spends, summed over all 25
  325. task-runs.
  326. **And since 2026-10-25 they are stated as a series** (D-20261025-cli-benchmarks-design-accepted).
  327. One run is not a verdict: two runs of the same commit have read 0.49 and 0.995. Each row is
  328. the median and the range over the CI runs in the window it names, and how many of them met the
  329. bar, written by `npm run agent-cost:row` from `benchmarks/results/agent-cli-bench/` and checked
  330. against that window by `scripts/claim-table-lock.test.ts`. Until then the token row said
  331. **0.699×**, from one run (`e6cff20`), and not met ([measured](https://burgee.interlace.tools/docs/benchmarks)).
  332. ### The two ways to ask the bundle question, and why both are here
  333. `burgee` is 24,528 bundled bytes and `cac` is 10,452, so the bare row reads **2.347× and it
  334. stays on this page**. It is also not the choice anyone makes. A program that picks `cac` and
  335. then wants its config file read, its shutdown bounded on every path out, and its cursor handed
  336. back on Ctrl-C installs three more packages — and *that* is what one `import` of burgee competes
  337. with ([measured](https://burgee.interlace.tools/docs/benchmarks)):
  338. | | the incumbent alone | + what you add to match burgee | ours |
  339. | :--- | ---: | ---: | ---: |
  340. | `cac` | 10,452 B | **98,484 B** | 24,528 B |
  341. | `commander` | 39,205 B | **127,249 B** | 55,514 B |
  342. | `yargs` | 111,994 B | **199,887 B** | 110,446 B |
  343. The additions are `cosmiconfig` (find and load a config file), `exit-hook` (run cleanup on
  344. every path out, including a signal) and `restore-cursor` (hand the terminal back), bundled
  345. together so a module two of them share is paid for once — which is what a real bundler does.
  346. **The rule that stops this being a rigged denominator:** a package may only enter a stack where
  347. this repository publishes a *graded drop-in* for it — a `compat-oracle` row whose pass rate
  348. comes from that package's own test suite. `seniority/cosmiconfig`, `closeout/exit-hook` and
  349. `closeout/restore-cursor` each have one, which is evidence we do the job rather than our word
  350. for it, and [`parity.test.ts`](./benchmarks/parity.test.ts) fails if an addition names a package
  351. with no active row. It is self-limiting on purpose: we cannot pad a stack with packages we
  352. merely resemble.
  353. And the capabilities with nothing to add against — `--schema`, `--mcp`, the `{ ok, data }`
  354. envelope on every command, agent detection, option relations and Standard Schema — are priced
  355. at **zero**. They are the part of the premium that is real and unpriced, and saying so is worth
  356. more than finding a package to charge for them.
  357. ### The three that are ratchets
  358. `cold-start-at-or-below-cac` and the two bare weight rows began as **≤ 1** and have a
  359. measured floor above it, and it is worth saying plainly rather than leaving as a to-do.
  360. `cac` is 10,452 bytes of parser and help renderer; burgee's 24,528 is that plus coercion,
  361. choices, relations, Standard Schema, configuration precedence, signal-bound shutdown, terminal
  362. restore and agent detection.
  363. Our `commander/command.js` is 33,487 bundled against commander's 27,226, and the front-end also
  364. carries a cross-platform spawn that cannot go lazy without giving up `parse()`'s synchronous
  365. contract and the 1418 / 1418 compat row that rests on it. And `import 'cac'` is one file in
  366. 4.2 ms where `import 'burgee'` is twenty-one in 20 ms. Closing them means deleting the product,
  367. not optimising it: the analysis is [D-102](./.sdlc/decisions/D-102.md), and the shrink that moved every
  368. non-default path behind `await import()` is [D-148](./.sdlc/decisions/D-148.md) ([measured](https://burgee.interlace.tools/docs/benchmarks)).
  369. So a bar we will never meet is no longer what these rows publish. Since
  370. [D-157](./.sdlc/decisions/D-157.md) each is a **downward-only ratchet**: a ceiling just above today's
  371. measurement, enforced on every benchmark run, that may be lowered by anyone and raised only by
  372. a new decision ([measured](https://burgee.interlace.tools/docs/benchmarks)).
  373. | Gate | Was | Ceiling | Set from, on 2026-09-27 |
  374. | :--- | :--- | ---: | :--- |
  375. | `cold-start-at-or-below-cac` | ≤ 1 | 1.55× | lowered 2026-10-11 after #898: the 26 CI runs since, mean 1.424, max 1.463; mean + 3 sd, rounded up to 0.05 |
  376. | `lighter-than-commander` | ≤ 1 | 1.42× | lowered 2026-10-19 after commander-front-end-diet: measured 1.416 in CI and locally, plus 80 B for CI's heavier build, rounded up to 0.005 (first set at 1.565) |
  377. | `lighter-than-cac` | ≤ 1 | 2.35× | measured 2.317, plus 80 B for CI's heavier build, rounded up to 0.05 |
  378. The ceilings live in [`claim-ratchets.json`](./.sdlc/bands/claim-ratchets.json) with their
  379. history, and [`claim-ratchets-lock.test.ts`](./scripts/claim-ratchets-lock.test.ts) refuses a
  380. step up that does not cite a newer decision. `npm run ratchets:propose` prints the lower
  381. ceiling each can move to from the latest measurement. The size comparison to lead with is still
  382. the at-parity rows above; the bare rows stay on the page because a suite that only showed the
  383. comparisons we win would be lying by selection.
  384. The agent rows are a different gap. B1 has run once, locally ([D-147](./.sdlc/decisions/D-147.md)),
  385. and neither row becomes ✅ until the weekly CI job measures it, which waits on a credential
  386. only the owner can mint ([D-150](./.sdlc/decisions/D-150.md)).
  387. Installed size is our largest number and it is larger than commander's. It buys no dependency
  388. outside the burgee family and six drop-in front ends, and it stays on the page either way: *not met* and
  389. *unmeasured* are different outcomes and neither collapses into the other. Every bundle figure
  390. in this section, including the ones that go against us, is written by `npm run readme:gates`
  391. from a fresh bundle of the build, and a push whose build measures anything else is refused
  392. ([`readme-gates-lock.test.ts`](./scripts/readme-gates-lock.test.ts)). The millisecond and
  393. installed-size figures come from the measurement published in
  394. [`benchmarks.mdx`](./apps/docs/content/docs/benchmarks.mdx) and pinned in
  395. [`comparison.mdx`](./apps/docs/content/docs/comparison.mdx).
  396. ---
  397. ## 🔐 Supply chain and continuity
  398. `npm i burgee` installs six packages, all of them from this repository, and installing any
  399. family package runs no install script
  400. ([`install-graph-lock`](./scripts/install-graph-lock.test.ts)). Every release is published
  401. through npm trusted publishing with SLSA provenance and no npm token
  402. ([`trusted-publishing-lock`](./scripts/trusted-publishing-lock.test.ts)). Everything is MIT, and
  403. each incumbent's own test suite is vendored in [`packages/compat-oracle`](./packages/compat-oracle/),
  404. so a fork keeps the conformance tests that tell it whether it still behaves the same.
  405. [Supply chain and continuity](https://burgee.interlace.tools/docs/supply-chain) has the install
  406. graph for each package and the check behind every statement.
  407. [Why it's built this way](https://burgee.interlace.tools/docs/why) gives the reasoning behind
  408. the family, and what it does not claim.
  409. ---
  410. ## 👥 Who is this for?
  411. | You are… | What burgee gives you |
  412. | :--- | :--- |
  413. | **Shipping your first CLI** | One file, no dependency outside the burgee family, help and `--json` for free |
  414. | **Maintaining a commander CLI** | A one-line import swap, graded against commander's own suite |
  415. | **Building for agents** | `--schema`, `--mcp` and a stable envelope, projected — never hand-written |
  416. | **On a platform team** | Plugins that work across commander, yargs and native syntax alike |
  417. ---
  418. ## 🧩 The family
  419. <p align="center">
  420. <img src="./brand-assets/burgee-flag-alive.svg" alt="burgee" width="70" />
  421. <img src="./brand-assets/roundel-flag-alive.svg" alt="roundel" width="70" />
  422. <img src="./brand-assets/flagstaff-flag-alive.svg" alt="flagstaff" width="70" />
  423. <img src="./brand-assets/caique-flag-alive.svg" alt="caique" width="70" />
  424. <br />
  425. <img src="./brand-assets/linegauge-flag-alive.svg" alt="linegauge" width="70" />
  426. <img src="./brand-assets/seniority-flag-alive.svg" alt="seniority" width="70" />
  427. <img src="./brand-assets/bellpull-flag-alive.svg" alt="bellpull" width="70" />
  428. <img src="./brand-assets/closeout-flag-alive.svg" alt="closeout" width="70" />
  429. <img src="./brand-assets/paratext-flag-alive.svg" alt="paratext" width="70" />
  430. <img src="./brand-assets/controlroom-flag-alive.svg" alt="controlroom" width="70" />
  431. <img src="./brand-assets/oxmutate-flag-alive.svg" alt="oxmutate" width="70" />
  432. </p>
  433. <p align="center">
  434. <sub>One family, cut from one ink, with the Interlace mark on every one of them and one
  435. light crossing all eleven. Only burgee flies the swallowtail: a roundel is rings, a
  436. flagstaff is a flag hoisted on a pole, a caique is a parrot, a line gauge is the printer's
  437. rule with its ticks cut through it, seniority is rank chevrons, a bellpull is the cord and
  438. its pull, a closeout is the double rule an accountant draws under a settled total, and a
  439. paratext is a page with its text cut away — only the margins are left — a control room is
  440. a console screen with its panes cut through it, and oxmutate is a block with one piece cut out
  441. and set apart, the small change a test has to notice. The
  442. light sweeps where a page can afford motion and parks itself under prefers-reduced-motion;
  443. the favicon and the npm READMEs take the still one. Every mark is burgee/brand output —
  444. eleven shapes, one declaration — regenerated by npm run brand and drift-checked in CI.</sub>
  445. </p>
  446. **burgee** declares; the **output stack** is what a CLI shows; the **foundation** is what it
  447. stands on. Each package is an independent product with its own README, installs on its own,
  448. and declares no dependency outside the burgee family.
  449. Eleven packages, one repository, one release pipeline and one supply chain to audit, with a
  450. single schema byte-identical in every tarball. Six leaves depend on nothing, and every other
  451. dependency points one way, down the [layers](https://burgee.interlace.tools/docs/concepts/family);
  452. the locks that hold each rule are named there. Releases are published through npm trusted
  453. publishing, with SLSA provenance and no npm token (`trusted-publishing-lock`). The case for one
  454. codebase is the number of things a user has to trust, not convenience.
  455. | | Layer | Package | What the layer owns | Migrates from | Status |
  456. | :-- | :-- | :-- | :-- | :-- | :-- |
  457. | **Engine** | argv, dispatch, manifest | [`burgee`](./packages/burgee/) | one declaration projected to help, `--json`, `--schema`, MCP, completions, types | commander · yargs · meow | released — `burgee@2.1.4` |
  458. | **Output stack** | colour | [`roundel`](./packages/roundel/) | one output policy, nine semantic tokens, a contrast-checked theme, and chalk's API over them | chalk · picocolors | released — `roundel@2.0.2` |
  459. | | render | [`flagstaff`](./packages/flagstaff/) | frame loop with a static projection; plugin host for spinners, progress, boxes, tables | ora · log-update · boxen · cli-table3 | released — `flagstaff@2.0.4` |
  460. | | prompt | [`caique`](./packages/caique/) | prompts that are flags first, and never hang | inquirer · clack · prompts | released — `caique@2.1.2` |
  461. | | screen | [`controlroom`](./packages/controlroom/) | keyboard-driven screens, inline or full-screen, over flagstaff's loop, each with a static projection | ink · @inkjs/ui | released — `controlroom@2.0.3` |
  462. | **Foundation** | text | [`linegauge`](./packages/linegauge/) | measure, wrap, truncate and slice styled text without the edge fraying | string-width · wrap-ansi · strip-ansi · slice-ansi | released — `linegauge@2.2.2` |
  463. | | config | [`seniority`](./packages/seniority/) | precedence across flag, env, project file, home file and default — with provenance | cosmiconfig · lilconfig · dotenv · rc | released — `seniority@2.0.3` |
  464. | | process | [`bellpull`](./packages/bellpull/) | run a subprocess; resolve the executable; return a result every caller can read | execa · cross-spawn · which | released — `bellpull@2.0.2` |
  465. | | lifecycle | [`closeout`](./packages/closeout/) | exit handlers that run once on every path, terminal restore, bounded deadline | signal-exit · exit-hook · restore-cursor | released — `closeout@2.0.2` |
  466. | | terminal | [`paratext`](./packages/paratext/) | hyperlinks, images, window title, clipboard, notifications, bell — each with a static fallback | ansi-escapes (OSC half) · terminal-link · term-img | released — `paratext@2.0.3` |
  467. All ten are released on npm at 1.x, with their public API under semver
  468. ([`SECURITY.md`](./SECURITY.md) says which releases are supported). Where an incumbent's own test suite has been vendored, the
  469. compat oracle grades the drop-in path against it and publishes the rate — including the ones
  470. not yet at 100% — on the [compatibility page](https://burgee.interlace.tools/docs/compatibility).
  471. Released is not the same as accepted: the four
  472. foundation packages began as `0.0.1` name reservations, were built out in waves F1–F4, and
  473. their intents under [`.sdlc/intents/cli-foundation-stack/`](./.sdlc/intents/cli-foundation-stack/)
  474. are still at `draft` — the human gate on the design has not run. The `bellpull` intent carries a kill gate, because a zero-dependency
  475. rival already holds the weight pitch in that layer, and its spec says plainly that the package
  476. was built before that gate was evaluated. The measurements behind the layers are in
  477. [`candidate-layers.md`](./.sdlc/research/candidate-layers.md) and
  478. [`replacement-map.md`](./.sdlc/research/replacement-map.md).
  479. ---
  480. ## 📚 Repo map
  481. | Path | Purpose |
  482. | :-- | :-- |
  483. | [`packages/burgee/`](./packages/burgee/) | The framework. `burgee` is the engine, `burgee/commander` the compat façade, `burgee/testing` the in-process harness (T1). |
  484. | [`packages/roundel/`](./packages/roundel/) | **roundel** — the colours a CLI carries: `roundel/policy` (`outputMode`, `colorLevel`), `roundel/tokens` (nine semantic tokens), `roundel/theme` (`fly()`, contrast-checked), `roundel/contrast`, and `roundel/chalk` — chalk 6's API over the tokens, graded by chalk's own suite (58 / 58, against a 58 / 58 control). Intent in [`.sdlc/intents/roundel/`](./.sdlc/intents/roundel/). |
  485. | [`packages/flagstaff/`](./packages/flagstaff/) | **flagstaff** — the staff the flag flies from: a frame loop with a static projection for agents, and the plugin host for spinners, progress, boxes and tables. Released; its one dependency is roundel. Intent in [`.sdlc/intents/flagstaff/`](./.sdlc/intents/flagstaff/). |
  486. | [`packages/caique/`](./packages/caique/) | **caique** — the parrot that always answers back: prompts that are flags first and never hang. Released, with graded `caique/inquirer` and `caique/clack` paths; intent in [`.sdlc/intents/caique/`](./.sdlc/intents/caique/). |
  487. | [`packages/linegauge/`](./packages/linegauge/) | **linegauge** — a printer's rule for text: width, wrap, truncate and slice, grapheme-correct over `Intl.Segmenter`. Released; intent in [`.sdlc/intents/linegauge/`](./.sdlc/intents/linegauge/). |
  488. | [`packages/seniority/`](./packages/seniority/) | **seniority** — which source outranks which, with provenance for every resolved value. Released; intent in [`.sdlc/intents/seniority/`](./.sdlc/intents/seniority/). |
  489. | [`packages/bellpull/`](./packages/bellpull/) | **bellpull** — pull here, work happens there: subprocesses with a structured result and a static projection. Released; intent in [`.sdlc/intents/bellpull/`](./.sdlc/intents/bellpull/). |
  490. | [`packages/closeout/`](./packages/closeout/) | **closeout** — settle and finish: exit handlers that run once, terminal restore, and a deadline so shutdown cannot hang. Released; intent in [`.sdlc/intents/closeout/`](./.sdlc/intents/closeout/). |
  491. | [`packages/paratext/`](./packages/paratext/) | **paratext** — everything around the output that is not the output: hyperlinks, images, window title, clipboard, notifications and the bell, each with a static fallback. Released; intent in [`.sdlc/intents/paratext/`](./.sdlc/intents/paratext/). |
  492. | [`packages/controlroom/`](./packages/controlroom/) | **controlroom** — where a system is run from: full-screen, keyboard-driven terminal screens with a static projection for every other caller, and `controlroom/ink`, ink's drop-in, graded by ink's own suite. Released; intent in [`.sdlc/intents/controlroom/`](./.sdlc/intents/controlroom/). |
  493. | [`packages/compat-oracle/`](./packages/compat-oracle/) | Internal, never published. Grades compatibility using the hosts' own suites, plus reference drivers that run the real incumbents for byte-for-byte comparison. |
  494. | [`examples/`](./examples/) | Demo CLIs and the conformance suite that runs every floor case on every host. |
  495. | [`apps/docs/`](./apps/docs/) | The front-door documentation site (Next.js + fumadocs), deployed at [burgee.interlace.tools](https://burgee.interlace.tools) with [`llms.txt`](https://burgee.interlace.tools/llms.txt) and a Markdown twin of every page. Every other package has its own site at `https://<package>.interlace.tools` — `apps/docs-<package>/`, on the shared chassis `apps/docs-chassis/` — named once in [`.github/vercel-apps.json`](./.github/vercel-apps.json). |
  496. | [`.sdlc/intents/`](./.sdlc/intents/) | Stage 1 + 2 artifacts of the AI-native SDLC: `intent.md` + `spec.md` per change, and the wave plan. |
  497. | [`.sdlc/research/`](./.sdlc/research/) | The evidence everything above rests on. |
  498. | [`.sdlc/brand/`](./.sdlc/brand/) | What each package is and what its mark has to say ([identity model](./.sdlc/brand/identity-model.md)), and the [brief](./.sdlc/brand/commission.md) a designer would work from. |
  499. ### The research
  500. Every claim in the design traces to one of these, and each records what it could **not**
  501. determine as well as what it found.
  502. - [`competitor-landscape.md`](./.sdlc/research/competitor-landscape.md) — the measured map:
  503. downloads, cold start, the compatibility bill, and why we implement rather than wrap.
  504. - [`tracker-gap-analysis.md`](./.sdlc/research/tracker-gap-analysis.md) — every open item in
  505. both trackers. Commander has 8; yargs has 211, 86% predating 2023. Six issues over nine
  506. years ask for machine-readable command structure, and the state of the art is
  507. regex-scraping `--help`.
  508. - [`agent-requirements.md`](./.sdlc/research/agent-requirements.md) — what agents need, and
  509. **three widely-quoted claims that do not survive verification**.
  510. - [`cli-market-requirements.md`](./.sdlc/research/cli-market-requirements.md) — ten production
  511. CLIs taken apart, including what the security market requires and where both leading
  512. scanners get it wrong.
  513. - [`architecture.md`](./.sdlc/research/architecture.md) — the diagrams.
  514. - [`lineage.md`](./.sdlc/research/lineage.md) — the six projects we follow, each reduced to a
  515. commitment.
  516. ---
  517. ## 🚦 Status
  518. | | What |
  519. | :-- | :-- |
  520. | ✅ **Working today** | The engine, the exit-code contract, the JSON envelope, help from the manifest, plugins with hook filters, and a `burgee/commander` façade that runs a real commander program |
  521. | 🔨 **Next** | The compatibility oracle, and the remaining commander surface |
  522. | ⛔ **Not yet true** | The dev loop, prompts, lazy commands and groups, and an adopter we did not write ourselves |
  523. Four locks — shape, process-reference, weight per entry point, and the adoption ladder — are
  524. each proven to fail before they passed. A compat façade does not reach 1.0 until its host's
  525. own suite passes **100%** (`C7`): both do today, which clears that gate and not the rest —
  526. burgee's 1.0 waits on the [floor](./apps/docs/content/docs/the-floor.mdx), 114 requirements of
  527. which the surfaces, the env/config/schema families and both façades are built. Until then the
  528. rate is published rather than the word "compatible" claimed. `linegauge` and `flagstaff` have
  529. already met every written 1.0 criterion and are 1.0: every requirement in each spec is built
  530. (13 of 13 and 12 of 12), and each drop-in path passes its incumbent's own suite in full
  531. (D-170).
  532. ---
  533. ## 🛠️ Working on burgee
  534. ```bash
  535. npm install
  536. npm test # every lock and unit test, exits non-zero on failure
  537. npm run dev # docs on http://localhost:3100
  538. npm run compat # grade burgee against commander's and yargs' own suites
  539. npm run brand # regenerate every brand surface from one declaration
  540. npm run brand:check # …and fail if any of them was hand-edited since
  541. ```
  542. ### Dogfooding
  543. This repo runs 12 Interlace ESLint plugins with **every rule on at `error`** and zero
  544. warnings allowed:
  545. | Scope | Plugins |
  546. | :-- | :-- |
  547. | Everywhere | `secure-coding` · `node-security` · `conventions` · `import-next` · `maintainability` · `modernization` · `modularity` · `operability` · `reliability` |
  548. | The docs app | `react-a11y` · `react-features` · `browser-security` |
  549. The rule list is computed from each plugin's own table, so a rule shipped in a plugin release
  550. is on here the day it lands — `browser-security` alone brings 41. Every exception is named in
  551. `eslint.config.mjs` with its reason.
  552. The three scoped to `apps/` are scoped for a reason: the engine never runs in a browser, so
  553. storage, `postMessage` and DOM-sink rules have nothing to say about it — but the docs app is
  554. a real browser application, and that is exactly the surface they grade.
  555. It earns its keep. During this project those rules caught a prototype-pollution vector in
  556. our own option parsing, a barrel import that cost ~5ms of startup, and a façade reaching for
  557. `process` behind the runtime seam.
  558. ---
  559. ## 🤝 Contributing
  560. The most useful thing anyone can send is **an adopter we did not write**: a real CLI ported
  561. over, and a report of what broke. That is the only compatibility evidence that counts, and
  562. every failure becomes a case in the conformance suite.
  563. [CONTRIBUTING.md](./CONTRIBUTING.md) has the loop, how a change is shaped before it is
  564. written, and what the checks will hold you to. [SECURITY.md](./SECURITY.md) is the private
  565. reporting path — please do not open a public issue for a vulnerability.
  566. - **Ported a CLI?** [Tell us what broke](https://github.com/ofri-peretz/burgee/issues) — the highest-value report we get
  567. - **Found a bug?** [Open an issue](https://github.com/ofri-peretz/burgee/issues) with the Node version and the exact argv
  568. - **Have an idea?** [Open an issue](https://github.com/ofri-peretz/burgee/issues/new)
  569. ---
  570. ## 📄 License
  571. MIT © [Ofri Peretz](https://github.com/ofri-peretz) — see [LICENSE](./LICENSE). Every
  572. published package ships the licence text in its tarball.
  573. <p align="center">
  574. <sub>Flying the flag for CLIs that humans and agents can both read.</sub>
  575. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.