Help

In this guide, we will be creating a command-line interface that provides different help mechanisms for end-users.

Help option

The most straightforward way to provide help for your CLI is by declaring a help option. In its simplest form, it has the following definition:


import { type Options } from 'tsargp';
export default {
  help: {
    type: 'help',
    names: ['--help'],
    synopsis: 'Prints this help message.',
  },
} as const satisfies Options;

You can enhance it with an introduction, usage and footer:


import { type Options, style, fg } from 'tsargp';
export default {
  help: {
    // ...
    sections: [
      {
        type: 'text',
        text: 'A command-line interface for <purpose>.',
      },
      {
        type: 'usage',
      },
      {
        type: 'groups',
        title: 'Options:', // heading for the default option group
        style: style(tf.underlined), // underlined option group headings
      },
      {
        type: 'text',
        text: `Refer to ${style(fg.brightBlack)}<website>${style(fg.default)} for support.`,
      },
    ],
  },
} as const satisfies Options;

You may also want to customize the layout of the groups section, e.g.:


import { type Options, HelpItem, style, tf, config } from 'tsargp';
 
config.helpPhrases[HelpItem.synopsis] = '💡 #0'; // option synopsis with emoji
 
export default {
  help: {
    // ...
    sections: [
      // ...
      {
        // ...
        layout: {
          names: { indent: 4 }, // indent option names by 4 spaces
          descr: { breaks: 1 }, // line feed before option descriptions
          param: { hidden: true }, // hide option parameter/examples
        },
        items: [HelpItem.synopsis, HelpItem.deprecated],
      },
      // ...
    ],
    styles: {
      descr: style(tf.italic), // italic description for this option
    },
  },
} as const satisfies Options;

Which, when invoked with --help, would render something like:


A command-line interface for <purpose>.
 
cli [--help]
 
Options:
 
    --help
              💡 Prints this help message.
 
Refer to <website> for support.

Help command

💡

Since this guide was first written, the enable subcommand attribute has been introduced. It supersedes help commands and offers a more convenient way to achieve what is described below. However, if you need parameter choices for the available command names, then what follows might still be relevant.

Another way to offer help is by defining a “help” subcommand. This method complements the help option from the previous example by providing a new syntax to obtain help for subcommands. For example, to present help for a subcommand called cmd, the following invocations would be equivalent:


cli help cmd
cli cmd --help

To achieve this, we have to define a “helper” subcommand that accepts the name of another subcommand for which the help message should be produced. Let’s start with the option definitions for the subcommands:


import { type Options } from 'tsargp';
 
const cmd1Opts = {
  // option definitions for cmd1, including its '--help'...
} as const satisfies Options;
 
const cmd2Opts = {
  // option definitions for cmd2, including its '--help'...
} as const satisfies Options;
 
const helpOpts = {
  name: {
    type: 'single',
    synopsis: 'The name of the subcommand.',
    choices: ['cmd1', 'cmd2'], // the names of subcommands
    preferredName: 'command name', // appears in error messages
    positional: true,
    required: true, // error if called without a subcommand name
  },
} as const satisfies Options;

Now we can define the main command options:


import { type Options, type OptionValues, parse } from 'tsargp';
 
export default {
  cmd1: {
    type: 'command',
    names: ['cmd1'],
    options: cmd1Opts,
    // ...
  },
  cmd2: {
    type: 'command',
    names: ['cmd2'],
    options: cmd2Opts,
    // ...
  },
  help: {
    type: 'command',
    names: ['help'],
    synopsis: 'Prints the help message of a subcommand.',
    options: helpOpts,
    async parse(param) {
      const vals = param as OptionValues<typeof helpOpts>;
      const opts = vals.name === 'cmd1' ? cmd1Opts : cmd2Opts;
      await parse(opts, ['--help'], { progName: vals.name }); // will throw the help message
    },
  },
} as const satisfies Options;

Since we are using a delegated parse call, we deliberately set the program name flag to the name of the target subcommand. Also, keep in mind that when word completion is in effect, the parsing callback will not be executed. Conversely, if it is executed, you need not worry about the completion index flag.