Auto generated help

The help information is auto-generated based on the information you have defined on your commands. The name, version, description, meta information, options, commands, environment variables and examples are displayed in the help.

To display the help you can invoke the help option (-h or --help) or the help command (help) on the main or on one of the sub commands. The help command needs to be registered manually.

To retrieve the help text programmatically you can use the .showHelp() and .getHelp() methods.

import { Command } from "@cliffy/command";

await new Command()
  .name("help-option-and-command")
  .version("0.1.0")
  .description("Sample description ...")
  .env(
    "EXAMPLE_ENVIRONMENT_VARIABLE=<value:boolean>",
    "Environment variable description ...",
  )
  .example(
    "Some example",
    "Example content ...\n\nSome more example content ...",
  )
  .parse();

denonodebun

$ deno run https://cliffy.io/examples/v1.2.1/command/help.ts --help

$ node run examples/command/help.ts --help

$ bun run examples/command/help.ts --help

You can use the .showHelp() method to output the help to stdout manually.

Commands that have sub-commands but no action handler automatically print the help when called without arguments. This behaviour can be disabled with .help({ auto: false }). See Auto help for container commands.

For example, to show the help programmatically inside an action handler, you can call .showHelp() directly:

import { Command } from "@cliffy/command";

const cmd = new Command()
  .name("git")
  .action(() => cmd.showHelp())
  .command("pull", "Pull changes from remote repository.")
  .action(() => console.log("Pulling..."))
  .command("fetch", "Fetch changes from remote repository.")
  .action(() => console.log("Fetching..."));

await cmd.parse();

You can also use this to refer to the current command instance inside the action handler:

import { Command } from "@cliffy/command";

await new Command()
  .name("git")
  .action(function () {
    this.showHelp();
  })
  .command("pull", "Pull changes from remote repository.")
  .action(() => console.log("Pulling..."))
  .command("fetch", "Fetch changes from remote repository.")
  .action(() => console.log("Fetching..."))
  .parse();

The .getHelp() method returns the auto generated help as string.

You can add some additional information to the help text with the .meta(name, value) method.

denonodebun

import { Command } from "@cliffy/command";

await new Command()
  .name("example")
  .version("1.0.0")
  .description("Example command.")
  .meta("deno", Deno.version.deno)
  .meta("v8", Deno.version.v8)
  .meta("typescript", Deno.version.typescript)
  .parse();

import { Command } from "@cliffy/command";

await new Command()
  .name("example")
  .version("1.0.0")
  .description("Example command.")
  .meta("node", process.version)
  .meta("v8", process.versions.v8)
  .meta("typescript", require('typescript').version)
  .parse();

import { Command } from "@cliffy/command";

await new Command()
  .name("example")
  .version("1.0.0")
  .description("Example command.")
  .meta("bun", Bun.version)
  .meta("v8", null /* Bun does not use v8 */)
  .meta("typescript", require('typescript').version)
  .parse();

The additional information is displayed below the command version in the auto generated help.

denonodebun

$ deno run example.ts --help
Usage:   example
Version: 0.1.0

deno: 1.16.1
v8: 9.7.106.2
typescript: 4.4.2

Description:

  Example command.

$ node run example.ts --help
Usage:   example
Version: 0.1.0

node: 1.16.1
v8: 9.7.106.2
typescript: 4.4.2

Description:

  Example command.

$ bun run example.ts --help
Usage:   example
Version: 0.1.0

bun: 1.16.1
v8: 9.7.106.2
typescript: 4.4.2

Description:

  Example command.

The .help() method can be used to customize the auto generated help. The help output is fully responsive and adapts to the terminal width by default.

import { Command } from "@cliffy/command";

await new Command()
  .help({
    // Show argument types.
    types: true, // default: false
    // Show hints.
    hints: true, // default: true
    // Enable/disable colors.
    colors: false, // default: true
    // Set the target width of the help output in columns.
    // Defaults to the terminal width (or 150 if not a TTY).
    width: 120,
    // Set the maximum width for the help output.
    maxWidth: 160,
  })
  .option("-f, --foo [val:number]", "Some description.", {
    required: true,
    default: 2,
  })
  .parse();

The help output is responsive by default: it reads the current terminal width and wraps text accordingly. The width option overrides the detected terminal width, and maxWidth caps it.

By default, when a command has sub-commands but no action handler, calling it without any arguments automatically prints the help text. This is the auto behaviour, which is enabled by default. You can disable it by passing { auto: false } to .help().

import { Command } from "@cliffy/command";

await new Command()
  .name("git")
  // Disable automatic help for container commands (help must be shown manually).
  .help({ auto: false })
  .command("pull", "Pull changes from remote repository.")
  .action(() => console.log("Pulling..."))
  .command("fetch", "Fetch changes from remote repository.")
  .action(() => console.log("Fetching..."))
  .parse();

The .help() method can be also used to override the help output. This overrides the output of the .getHelp() and .showHelp() methods which are used by the help option and help command. The help handler will also be used for all sub commands, but can be overridden in each sub command separately.

import { Command } from "@cliffy/command";

await new Command()
  .help("My custom help")
  // Can be also a function.
  .help(() => "My custom help")
  .parse();

The -h and --help option flag prints the auto generated help to stdout.

The short flag -h prints only the first line of each option and command description. With the long flag (--help) the full description is printed for each option and command.

Optionally you can also register the pre-defined help command to display the help.

The help option is completely customizable with the .helpOption() method. It has the same arguments as the normal .option() method. With the first argument you specify the flags followed by the description. The third argument can be an action handler or an options object. The second and third arguments are optional.

import { Command } from "@cliffy/command";

await new Command()
  .helpOption("-i, --info", "Print help info.", function (this: Command) {
    console.log("some help info ...", this.getHelp());
  })
  .parse();

You can also override the default options of the help option. The options are the same as for the .option() method.

import { Command } from "@cliffy/command";

await new Command()
  .helpOption(" -x, --xhelp", "Print help info.", { global: true })
  .parse();

To disable the help option you can pass false to the .helpOption() method.

import { Command } from "@cliffy/command";

await new Command()
  .helpOption(false)
  .parse();

The --version and -V option flag prints the version number defined with the version() method. The version number will also be displayed in the auto generated help. If the long --version option is used, the long format will be printed including command name and all meta data defined with the .meta() method.

import { Command } from "@cliffy/command";

await new Command()
  .version("0.1.0")
  .parse();

denonodebun

$ deno run https://cliffy.io/examples/v1.2.1/command/version_options.ts -V
0.0.1

$ deno run https://cliffy.io/examples/v1.2.1/command/version_options.ts --version
0.0.1

$ node run examples/command/version_options.ts -V
0.0.1

$ node run examples/command/version_options.ts --version
0.0.1

$ bun run examples/command/version_options.ts -V
0.0.1

$ bun run examples/command/version_options.ts --version
0.0.1

The version option is completely customizable with the .versionOption() method. It has the same arguments as the normal .option() method. With the first argument you specify the flags followed by the description. The third argument can be an action handler or an options object. The second and third arguments are optional.

import { Command } from "@cliffy/command";

await new Command()
  .version("0.1.0")
  .versionOption(
    " -x, --xversion",
    "Print version info.",
    function (this: Command) {
      console.log("Version: %s", this.getVersion());
    },
  )
  .parse();

You can also override the default options of the version option. The options are the same as for the .option() method.

import { Command } from "@cliffy/command";

await new Command()
  .version("0.1.0")
  .versionOption(" -x, --xversion", "Print version info.", { global: true })
  .parse();

The version option can be also disabled.

import { Command } from "@cliffy/command";

await new Command()
  .versionOption(false)
  .parse();

You can add some examples for your command which will be displayed in the auto generated help.

import { red } from "@std/fmt/colors";
import { Command } from "@cliffy/command";

await new Command()
  .name("examples")
  .example(
    "example name",
    `Description ...\n\nCan have multiple lines and ${red("colors")}.`,
  )
  .parse();

denonodebun

$ deno run https://cliffy.io/examples/v1.2.1/command/examples.ts help

$ node run examples/command/examples.ts help

$ bun run examples/command/examples.ts help