Climax@rhythmjs/climax
Command help
Answer --help, -h and help <command> from the commands you already registered.
On this page
@rhythmjs/climax is a plain package of opt-in extras for @rhythmjs/cli. Each feature lives under its own subpath, and nothing in it is part of the core. The first feature is help.
Install#
bun add @rhythmjs/climax @rhythmjs/cli @rhythmjs/rhythmDocument a command#
commandHelp is ordinary middleware that carries documentation and does nothing at runtime, so the command stays the single source of truth: what is documented is what runs. Put it before the handler.
import { Rhythm, mount } from "@rhythmjs/rhythm";
import { RhythmCli } from "@rhythmjs/cli";
import { toCliHandler } from "@rhythmjs/cli/run";
import { commandHelp } from "@rhythmjs/climax/help/command";
import { documented } from "@rhythmjs/climax/help/documented";
import { helpModule } from "@rhythmjs/climax/help/module";
import { log } from "@rhythmjs/cli/output";
const cli = documented(new RhythmCli({ name: "app" })).cmd(
"deploy :environment",
commandHelp({
summary: "Deploy the app",
description: "Builds and ships the current commit.",
examples: ["app deploy prod"],
}),
(ctx) => log(ctx, `Deploying to ${ctx.params.environment}`),
);
const app = new Rhythm()
.use(helpModule.forRoot({ name: "app", description: "Example app" }))
.use(mount(cli));
process.exitCode = await toCliHandler(app)(Bun.argv.slice(2));Wrap the cli with documented()#
A RhythmCli does not expose its commands, so documented(cli) (from @rhythmjs/climax/help/documented) records every cmd() and use() call on the cli and returns the same cli. Wrap every cli you want in help, including mounted children: a cli that is not wrapped contributes nothing, silently.
Register the module first#
helpModule is never handed the cli. Like the OpenAPI module, it documents the app it is used in by scanning that app's sources, and it follows documented clis mounted into it, recursively. Middleware runs in order, and help answers without calling next(), so add helpModule.forRoot() before mount(cli).
name is the program name shown in Usage: lines and description is printed above the index. Used outside an app, the module throws a clear error instead of rendering an empty page. When it answers help it prints through ctx.log and sets the exit code to 1 for an unknown topic.
What it prints#
Help is triggered by --help or -h anywhere before --, or by help as the first word. What follows decides the output.
$ app --help
Example app
Usage: app <command> [options]
Commands:
deploy <environment> Deploy the app
user add <name> Add a user
Run `app help <command>` for details on a command.$ app help deploy
Usage: app deploy <environment>
Deploy the app
Builds and ships the current commit.
Examples:
$ app deploy prod- No topic prints the index of every command.
- A command (
app help deploy,app deploy prod -h) prints usage, summary, description, options and examples. - A prefix (
app user --help) lists the subcommands under it. - An unknown topic prints
Unknown command: …followed by the index, and exits with code 1. Every other case exits with 0.
Help reads raw argv, so the value of another flag (--env prod) counts as a word of the topic. Put --help first or use app help <command> when a flag value could be mistaken for a command.
Mark commands#
commandHelp also takes deprecated (true or a message, shown in the index and on the command page) and hidden, which leaves a command out of the output while it still runs. Undocumented commands are listed by default, with usage and no summary; set includeUndocumented: false on the module to show only documented ones, or includeHidden: true to show hidden ones too.
Options have their own page: see options and inheritance. Every export is listed in the API reference.