rhythmjs

Search documentation

Search guides, the tutorial and every package.

On this page

Document an option#

optionHelp describes a flag. The cli's parser is schema-less, so it is documentation only: it does not validate, coerce or default anything at runtime. Pair it with withParsedArgv() from @rhythmjs/cli/argv to read the flag.

TypeScript
import { documented } from "@rhythmjs/climax/help/documented";
import { commandHelp } from "@rhythmjs/climax/help/command";
import { optionHelp } from "@rhythmjs/climax/help/option";
import { log } from "@rhythmjs/cli/output";

const cli = documented(new RhythmCli()).cmd(
  "deploy :environment",
  commandHelp({ summary: "Deploy the app" }),
  optionHelp({ name: "force", alias: "f", description: "Skip checks", default: false }),
  optionHelp({ name: "target", type: "string", required: true, description: "Deploy target" }),
  (ctx) => {
    log(ctx, `Deploying to ${ctx.params.environment}`);
  },
);

name and alias are written without dashes. type is the placeholder shown after the flag, and required and default become notes after the description.

Text
Options:
  -f, --force            Skip checks (default: false)
      --target <string>  Deploy target (required)

Share options with later commands#

Put optionHelp through .use() and it applies to every command registered after it, the same way any middleware wraps only what follows. Use it for flags that more than one command reads.

TypeScript
const cli = documented(new RhythmCli())
  .cmd("version", (ctx) => log(ctx, "1.0.0")) // no --json listed
  .use(optionHelp({ name: "json", description: "Print JSON" }))
  .cmd("deploy :environment", deploy) // --json listed
  .cmd("status", status); // --json listed

Passed as a command handler, as in the previous section, it applies to that command only.

Nested clis#

A cli mounted with .use(mount(child)) is walked too, provided the child is also wrapped with documented(), and it inherits the options registered before the mount. Options a child registers stay in the child and never leak into the parent or its siblings.

Commands use full paths, so a child's commands carry their whole command string (user add :name), and that is what help prints.

TypeScript
const user = documented(new RhythmCli()).cmd(
  "user add :name",
  commandHelp({ summary: "Add a user" }),
  addUser,
);

const cli = documented(new RhythmCli())
  .use(optionHelp({ name: "json", description: "Print JSON" }))
  .use(mount(user));

app --help lists user add <name>, and app user --help lists the subcommands under user. Both show --json, because it was registered before the mount.

Custom output#

The module carries a helpService. Keep the module in a variable, add it with .use(help), and call it from there. commands() returns the structured list, one entry per command with segments, usage, summary, description, examples, deprecated and options, and render(topic) returns the lines for a topic. Use the first to feed another renderer, such as Markdown for your docs.

TypeScript
const help = helpModule.forRoot({ name: "app" });
const app = new Rhythm().use(help).use(mount(cli));

const docs = help.helpService.commands();