burgee
API reference

burgee/help

Every export of burgee/help, with its signature and doc comment: renderHelp, plus 3 types.

burgee/help — the help renderer, by itself. See index.ts for why it is not in the barrel.

import { renderHelp } from 'burgee/help';

Functions

renderHelp

Render help for one node — a runnable command, a group, or both — as text. Deterministic for a given node and width; a snapshot suite pins it. With color off — the default — a theme changes nothing; with it on, only ANSI is added.

function renderHelp(manifest: Manifest, node: CommandNode, opts?: HelpOptions & {
    format?: 'text';
}): string;

function renderHelp(manifest: Manifest, node: CommandNode, opts: HelpOptions & {
    format: 'markdown';
}): Promise<string>;
ParameterType
manifestManifest
nodeCommandNode
opts (optional)HelpOptions & { format?: 'text'; }

Returns string

Interfaces

HelpOptions

interface HelpOptions {
    /** Columns available; 100 when unknown, never `process.stdout` directly (H3). */
    width?: number;
    /** Show type hints such as `[string]`; off by default (H6). */
    verbose?: boolean;
    /** Apply colour (R7). Off by default: the renderer is pure, so the TTY and NO_COLOR decision stays with the caller. */
    color?: boolean;
    /**
     * Replaces the default styling token by token; read only when `color` is on. See
     * `HelpTheme` for the lines it leaves plain: the `Usage:` command name and `$ example`.
     */
    theme?: HelpTheme;
    /**
     * The commands to list, in place of the node's visible children: each by its path from the
     * node, with what it takes (`config get <key>`), under the heading of the child it is reached
     * through. The engine passes every command that runs when they fit (`listed` in `usage.ts`).
     */
    commands?: readonly CommandNode[];
    /**
     * More rows for `Global options:`, after `--json`, `--help` and `--schema`: the global flags
     * the engine parses for this command (`--color`, `--quiet`, `--timeout`; agent-lint-conformance
     * R1–R3), passed in by the engine like `commands`, so this renderer carries none of their words.
     */
    globals?: readonly {
        term: string;
        text: string;
    }[];
    /**
     * The run's language (`localised-human-surfaces` R1): every heading, row text and the root's
     * line for agents are passed through it once laid out in English (the node's own description
     * arrives already in the run's language, R5). The engine hands in a pack's translator; absent,
     * it is the identity, and help is byte-for-byte what it was.
     */
    say?: (english: string) => string;
    /**
     * Words the engine adds to the root's line for agents: `AGENTS.md`, when one sits beside the
     * binary (agent-skill R4). Passed in like `commands`, so this renderer looks for no file.
     */
    forAgents?: string;
}

Types

HelpTheme

Per-token styling for help (R7). A user who has roundel passes its tokens; a user who does not gets the defaults. Help reads heading, command, flag and value; the others are accepted so one theme object serves the whole output stack.

type HelpTheme = Partial<Record<HelpToken, (s: string) => string>>;

HelpToken

The token names of roundel's R3, typed structurally: help never imports the tokens (U13).

type HelpToken = 'error' | 'warn' | 'ok' | 'hint' | 'muted' | 'command' | 'flag' | 'value' | 'heading';

On this page