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
$ yarn add @oclif/core --latest
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": "./lib/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) {
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, Topic} 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,
// or showCommandHelp
showHelp(args: string[]): void {
}
// display the root help of a CLI
showRootHelp(): void {
}
// display help for a topic
showTopicHelp(topic: Topic): void {
}
// display help for a command
showCommandHelp(command: Command): void {
}
// 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
// displayed for the root help
formatRoot(): string {
}
// the formatting for an individual topic
formatTopic(topic: Config.Topic): string {
}
// the formatting for a list of topics
protected formatTopics(topics: Config.Topic[]): string {
}
// the formatting for a list of commands
formatCommands(commands: Config.Command[]): string {
}
// the formatting for an individual command
formatCommand(command: Config.Command): string {
}
}
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, Topic} from '@oclif/core';
export default class MyHelpClass extends Help {
public showCommandHelp(command: Config.Command) {
console.log('Display my custom command help!')
}
}
Then run help for any command.
$ my-cli login --help
Display my custom command help!
Building custom help classes in JavaScript projects
These examples above followed a TypeScript project. For JavaScript project with an example help file at "[project root]/src/help.js" would have a package.json with the helpClass
defined:
{
// ...
"oclif": {
"helpClass": "./src/help"
// ...
}
// ...
}
The imports are handled slightly different for JavaScript projects but the rest of the help class mimic the TypeScript examples above, except without type annotations.
const {HelpBase} = require('@oclif/core');
module.exports = class MyHelpClass extends HelpBase {
showHelp(args) {
console.log('This will be displayed in multi-command CLIs')
}
showCommandHelp(command) {
console.log('This will be displayed for a single command')
}
}
const {Help} = require('@oclif/core');
module.exports = class MyHelpClass extends Help {
showHelp(args) {
}
showRootHelp() {
}
showTopicHelp(topic) {
}
showCommandHelp(command) {
}
formatRoot() {
}
formatTopic(topic) {
}
formatTopics(topics) {
}
formatCommands(commands) {
}
formatCommand(command) {
}
}