Help Classes

Out of the box oclif provides a great help experience for CLIs. Users can invoke help with the --help flag.

$ my-cli login --help

If you want your CLI to have an explicit help command, add @oclif/plugin-help as an oclif plugin in your config.

$ my-cli help

Custom Help

To get started, first define the filepath to your help class in oclif's config in package.json. This is a relative path to the help class, without a file extension.

For this example, the help class will be created in a file at "[project root]/src/help.ts".

{
  "oclif": {
    "helpClass": "./dist/help"
  }
}

From here there are two paths, implement the HelpBase abstract class yourself or overwrite the parts of the default Help class you want to customize (ex: how command usage is displayed). We recommend the latter approach but cover both below.

Extending the HelpBase class

The HelpBase abstract class provides a starting point requiring the minimum needed methods implemented to be compatible with oclif.

import {Command, HelpBase} from '@oclif/core';

export default class CustomHelp extends HelpBase {
  showHelp(args: string[]) {
    console.log('This will be displayed in multi-command CLIs')
  }

  showCommandHelp(command: Command.Loadable) {
    console.log('This will be displayed in single-command CLIs')
  }
}

The showHelp method is called by oclif to display help in multi-command CLIs, while showCommandHelp is called directly for single-command CLIs.

The class is instantiated with a config property that provides helpful context for constructing your custom output.

To see an example of what is possible take a look at the source code for the default Help class exported from @oclif/core.

Extending the default Help class

The default Help class provides many method “hooks” that make it easy to override the particular parts of help's output you want to customize.

import {Command, Help, Interfaces} from '@oclif/core'

export default class MyHelpClass extends Help {
  // acts as a "router"
  // and based on the args it receives
  // calls one of showRootHelp, showTopicHelp,
  // the formatting for an individual command
  formatCommand(command: Command.Loadable): string {}

  // the formatting for a list of commands
  formatCommands(commands: Command.Loadable[]): string {}

  // displayed for the root help
  formatRoot(): string {}

  // the formatting for an individual topic
  formatTopic(topic: Interfaces.Topic): string {}

  // the default implementations of showRootHelp
  // showTopicHelp and showCommandHelp
  // will call various format methods that
  // provide the formatting for their corresponding
  // help sections;
  // these can be overwritten as well

  // the formatting responsible for the header
  // the formatting for a list of topics
  protected formatTopics(topics: Interfaces.Topic[]): string {}

  // display help for a command
  showCommandHelp(command: Command.Loadable): void {}

  // or showCommandHelp
  showHelp(args: string[]): void {}

  // display the root help of a CLI
  showRootHelp(): void {}

  // display help for a topic
  showTopicHelp(topic: Interfaces.Topic): void {}
}

To see the default implementation of these methods take a look at the default Help class exported from @oclif/core.

To start experimenting, define showCommandHelp in your custom help class and change the output.

import {Command, Help} from '@oclif/core';

export default class MyHelpClass extends Help {
  public showCommandHelp(command: Command.Loadable) {
    console.log('Display my custom command help!')
  }
}

Then run help for any command.

$ my-cli login --help
Display my custom command help!