@phnx-labs/cli-docs

Generate a CLI's command reference from its Commander program. One call writes three files:

• command-index.md: every command grouped, one line each
• command-index.json: the full structured surface (arguments, options, choices, defaults, examples, notes)
• command-reference.html: a self-contained page with the command tree in a sticky sidebar and instant search

The walk reads the registered Commander tree, so the reference cannot drift from what the CLI accepts. It is deterministic: no model, no help-text parsing, and a codepoint sort so macOS and Linux produce the same bytes.

Use

bun add -d @phnx-labs/cli-docs

scripts/gen-docs.ts in your CLI:

import { runReferenceScript } from '@phnx-labs/cli-docs';
import { buildProgram } from '../src/index.ts';
import { getHelpSections } from '../src/lib/help.ts'; // optional: examples + notes

runReferenceScript(buildProgram(), {
  bin: 'browser',
  description: 'Drive real browsers from the terminal.',
  helpSections: getHelpSections,
  outDir: 'docs',
  regenerate: 'bun scripts/gen-docs.ts',
});

bun scripts/gen-docs.ts           # write docs/command-{index.md,index.json,reference.html}
bun scripts/gen-docs.ts --check   # CI: exit 1 and name each stale file

A command or option with no description fails generation, so a reference never ships an empty entry. Hidden commands ({ hidden: true }) are left out.

API

• runReferenceScript(program, options, argv?): write, or check with --check
• writeReference(program, { ...options, outDir, check? }): returns { groups, commands, stale }
• buildReference(program, options): the three files' contents, no I/O
• walk, rootNode, renderMarkdown, renderJson, renderHtml, auditReference: the pieces

Options: bin and regenerate (required), title, description, helpSections(cmd), excluded.

License

FSL-1.1-Apache-2.0