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:


export default {
  : {
    : 'help',
    : ['--help'],
    : 'Prints this help message.',
  },
} as  satisfies ;

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


export default {
  : {
    : 'help',
    // ...
    : [
      {
        : 'usage',
        : { : 'A command-line interface for <purpose>.' },
        : { : 2 }, // line feeds from heading
      },
      {
        : 'groups',
        : {
          : 'Options:', // heading for the default option group
          : [.], // underlined group headings
          : 1, // line feeds from previous section (+1)
        },
        : { : 2 }, // line feeds from heading
      },
      {
        : 'text',
        : {
          : `Refer to ${new ('https://example.com')} for support.`,
          : 1, // line feeds from previous section (+1)
        },
      },
    ],
  },
} as  satisfies ;

You can also customize the layout of the groups section, e.g.:


.[.] = '💡 #0'; // option synopsis with emoji
 
export default {
  : {
    : 'help',
    // ...
    : [
      // ...
      {
        : 'groups',
        // ...
        : {
          : { : 4 }, // indent option names by 4 spaces
          : { : 1 }, // line feed before option descriptions
          : null, // hide option parameter/examples
          : [., .],
        },
      },
      // ...
    ],
    : {
      : [.], // italic description for this option
    },
  },
} as  satisfies ;

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 https://example.com/ 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 create a “helper” subcommand that accepts the name of another subcommand for which the help message should be produced. Below is an example where we define the options for the subcommands, and then define those for the main command:


const  = {
  // option definitions for cmd1, including its '--help'...
} as  satisfies ;
 
const  = {
  // option definitions for cmd2, including its '--help'...
} as  satisfies ;
 
const  = {
  : {
    : 'single',
    : 'The name of the subcommand.',
    : ['cmd1', 'cmd2'], // the names of subcommands
    : 'command name', // appears in error messages
    : true,
    : true, // error if called without a subcommand name
  },
} as  satisfies ;
 
export default {
  : {
    : 'command',
    : ['cmd1'],
    : ,
    // ...
  },
  : {
    : 'command',
    : ['cmd2'],
    : ,
    // ...
  },
  : {
    : 'command',
    : ['help'],
    : 'Prints the help message of a subcommand.',
    : ,
    async () {
      const  =  as <typeof >;
      const  = . === 'cmd1' ?  : ;
      await (, ['--help'], { : .,  }); // will throw the help message
    },
  },
} as  satisfies ;

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.