Help

The help plugin adds --help / -h to all commands and auto-generates formatted help output. On terminals with color support, the output is colorized automatically; in docs and non-color environments it falls back to plain text.

Usage

import { Crust } from "@crustjs/core";
import { helpPlugin } from "@crustjs/plugins";

const main = new Crust("my-cli")
  .use(helpPlugin())
  .run(() => { /* ... */ });

await main.execute();

No configuration needed. The plugin injects a --help flag into every command (including subcommands) during the setup phase.

What It Does

Flag Injection

During setup, the plugin adds the following flag to the root command and all subcommands recursively:

help: {
  type: "boolean",
  short: "h",
  description: "Show help",
}

Help Display

The middleware intercepts execution in two cases:

--help is passed — Renders help and stops execution
Container command — A command with subcommands but no run() handler automatically shows help

Help Output Format

my-cli - My CLI tool

USAGE:
  my-cli <command> [options]

COMMANDS:
  build      Build the project
  dev        Start dev server

OPTIONS:
  -h, --help, --no-help          Show help
  -v, --version, --no-version    Show version number

The help text includes these sections (when applicable):

Section	When shown
Header	Always — `command-path - description`
USAGE	Always — auto-generated or custom `meta.usage`
COMMANDS	When the command has subcommands
ARGS	When the command has positional arguments
OPTIONS	When the command has flags

Boolean flags are shown with both supported canonical forms:

--verbose, --no-verbose

Default values are appended inline when the command definition includes them:

[name]              Who to greet [default: "world"]
--port              Port number [default: 3000]

Usage Line

The usage line is auto-generated from the command definition:

my-cli <command> [name] [options]

<command> — shown for container commands (subcommands exist, no run)
<arg> — required positional argument
[arg] — optional positional argument
arg... — variadic argument
[options] — shown when flags exist

Override the auto-generated usage with meta.usage:

new Crust("deploy")
  .meta({ usage: "deploy <env> [--dry-run]" })
  // ...

`renderHelp` Function

The renderHelp function is exported separately for generating help text programmatically:

import { renderHelp } from "@crustjs/plugins";

const helpText = renderHelp(myCommand, ["my-cli", "deploy"]);
console.log(helpText);

// path is optional — defaults to [command.meta.name]
const helpText2 = renderHelp(myCommand);

Parameters:

command — The command to render help for
path (optional) — The command path array (e.g., ["my-cli", "deploy"]). Defaults to [command.meta.name]

Returns: A formatted help string.

The `--` Separator

--help is not recognized after the -- separator — arguments after -- are treated as raw args. See the -- separator for details.

Subcommand Help

Each subcommand gets its own --help:

my-cli --help              # Help for root command
my-cli build --help        # Help for build subcommand
my-cli create plugin --help # Help for nested subcommand

Type

function helpPlugin(): CrustPlugin;
function renderHelp(command: CommandNode, path?: string[]): string;

The help output includes the full command path:

my-cli build - Build the project

USAGE:
  my-cli build [options]

OPTIONS:
  --minify, --no-minify         Disable minification
  -h, --help, --no-help         Show help

On this page