Help messages

Help output is built from the definition, so it cannot drift from what the CLI actually accepts. There is no built-in --help flag. Define one and print the message yourself. You decide when and how it appears.

const cli = defineCLI({
  cliName: "listy",
  options: {
    help: {
      aliases: ["h"],
      exclusive: true,
      schema: z.boolean().optional(),
      coerce: coerce.boolean,
      meta: { description: "Show the help message." },
    },
  },
});

cli.onExecute(result => {
  if (result.options.help && cli.generateCliHelpMessage) {
    console.log(cli.generateCliHelpMessage());
    return;
  }
});

generateCliHelpMessage and generateSubcommandHelpMessage are attached to the CLI and to every subcommand on the first run or runAsync call. That is why they are optional in the type. printCliHelp and printSubcommandHelp do the same and write straight to the console. All four are listed in Help message.

Built-in styles

import { helpMessageStyles } from "@staticbolt/args-parser";

console.log(cli.generateCliHelpMessage({ style: helpMessageStyles.dracula }));

Style	Notes
`default`	Used when you pass no style.
`dracula`
`nord`
`solarizedDark`
`gruvboxDark`
`monokai`
`oneDark`
`catppuccin`
`noColors`	Plain text. Good for piping or for CI logs.
`html`	Wraps each part in a `<span>`. See below.

A custom style

HelpMessageStyle takes the parts that you want to change and, optionally, a style to fall back to for the rest.

import { HelpMessageStyle, helpMessageStyles } from "@staticbolt/args-parser";
import chalk from "chalk";

const myStyle = new HelpMessageStyle(
  {
    title: chalk.bold.magenta,
    option: chalk.yellow,
    argument: chalk.green,
  },
  helpMessageStyles.default
);

console.log(cli.generateCliHelpMessage({ style: myStyle }));

Every part you can style is listed in Help message.

Layout and wording

PrintHelpOptions controls spacing, section titles, and the wording of the optional and default markers.

cli.generateCliHelpMessage({
  optionsTitle: "FLAGS",
  optionalKeyword: "(optional)",
  defaultKeyword: "(default: {{ value }})",
  emptyLines: 1,
});

The full table of options and their defaults is in Help message.

As HTML

Use the html style with the html markdown renderer, and drop the result into a <pre>:

import { generateCliHelpMessage, helpMessageStyles } from "@staticbolt/args-parser";

import { listyCLI } from "./cli.ts";

const htmlHelp = generateCliHelpMessage(listyCLI, {
  style: helpMessageStyles.html,
  markdownRenderer: "html",
});

const pre = document.createElement("pre");
pre.innerHTML = htmlHelp;
document.body.append(pre);

Markdown inside descriptions is wrapped in span._markdown, so it can be styled with plain CSS:

span._markdown * {
  white-space: initial;
}