Skip to main content

Commands

A basic command looks like the following in TypeScript:

import {Command} from '@oclif/core'

export class MyCommand extends Command {
  static description = 'description of this example command'

  async run(): Promise<void> {
    console.log('running my command')
  }
}

The only part that is required is the run function. Accept user input with arguments and flags.

In JavaScript:

const {Command} = require('@oclif/core')

class MyCommand extends Command {
  async run() {
    console.log('running my command')
  }
}

MyCommand.description = 'description of this example command'

module.exports = MyCommand

Note that the following examples will be in TypeScript. As JavaScript does not yet have static class properties, you will have to add them to the class after it is declared like we did with the description above.

Avoiding Timeouts​

In order to avoid command executions running indefinitely, oclif will terminate the node process 10 seconds after Command.run resolves. This means that all command logic inside the run method should either run synchronously or should return a Promise. This will allow the entire command to run before the 10 second timeout starts.

In other words, if you execute a promise in Command.run without a awaiting it, then the command will likely timeout before it's completed.

Other Command Options​

See the base class to get an idea of what methods can be called on a command.

import {Command, Flags} from '@oclif/core'

export class MyCommand extends Command {
  static summary = 'A brief overview of your command.'
  static description = `
An in-depth description of the command.
It can be multiline.
`

  // hide the command from help
  static hidden = false

  // custom usage string for help
  // this overrides the default usage
  static usage = 'mycommand --myflag'

  // examples to add to help
  // <%= config.bin %> resolves to the executable name
  // <%= command.id %> resolves to the command name
  static examples = [
    // Examples can be simple strings
    '<%= config.bin %> <%= command.id %> --help',
    // Or objects that provide a description of the example command
    {
      description: 'Force the command to execute',
      command: '<%= config.bin %> <%= command.id %> --force',
    }
  ]

  // this makes the parser not fail when it receives invalid arguments
  // defaults to true
  // set it to false if you need to accept a variable number of arguments
  static strict = false

  // define aliases that can execute this command.
  static aliases = ['alternate:name:for:this:command']

  // Set to true if you want to add the --json flag to your command.
  // oclif will automatically suppress logs (if you use this.log, this.warn, or this.error) and
  // display the JSON returned by the command's run method.
  static enableJsonFlag = true

  async run() {
    // show a warning
    this.warn('uh oh!')
    // exit with an error message
    this.error('uh oh!!!')
    // exit with status code
    this.exit(1)
  }
}

Command Methods​

The following assumes you are in the run() method of an oclif command.

this.log(message: string)​

Output message to stdout (non-blocking). console.log() works fine too, but that is a blocking call and won't be automatically suppressed when the --json flag is present. This uses util.format() which behaves the same as console.log().

this.log('hello, world!')

this.warn(message: string | Error)​

Display an error or message as a warning

this.warn('uh oh!')
this.warn(new Error('uh oh!'))

this.error(message: string | Error, options?: {code?: string, exit?: number, ref?: string; suggestions?: string[];})​

Display error and exit. Also add a code to error object or exit status.

this.error('uh oh!', {exit: 2})
this.error(new Error('uh oh!'))

The options object has the following options:

  • exit — exit code to use
  • code — a unique error code for the type of error
  • suggestions — an array of suggestions for a user to try next that may be useful or provide additional context
  • ref — a url to documentation related to this error or fixing it

The message, code, suggestions, ref properties will be displayed when an error is shown. Reusable Error classes can be created that display the optional outputs above by implementing the PrettyPrintableError interface from the Errors namespace from @oclif/core and this.error will handle them appropriately.

These errors are friendly and won't show a traceback unless debugging is enabled with DEBUG=*.

import {CLIError} from '@oclif/errors'

throw new CLIError('my friendly error')

Any error caught by the command of this CLIError type will be shown without traceback.

this.exit(code: number = 0)​

Exit process. Defaults to status 0.

this.exit()
this.exit(1)

this.logToStderr(message: string)​

Log a message to the terminal's stderr.

this.jsonEnabled()​

Returns to true if the --json flag is present and enableJsonFlag is set to true

this.toSuccessJson(result: unknown)​

Modify the command's success JSON output before it's displayed to the user.

this.toErrorJson(result: unknown)​

Modify the command's error JSON output before it's displayed to the user.