custom-commands.md

Custom commands

Serverless Framework plugins can define custom CLI commands.

These commands can then be called by users, for example: serverless my-command.

class MyPlugin {
  constructor() {
    this.commands = {
      'my-command': {
        lifecycleEvents: ['resources', 'functions'],
      },
    };
  }
}

module.exports = MyPlugin;

A CLI Command that can be called by a user, e.g. serverless foo. A Command has no logic, but simply defines the CLI configuration (e.g. command, parameters) and the Lifecycle Events for the command. Every command defines its own lifecycle events.

Lifecycle events

By default, a command has no logic. Use lifecycle event hooks to add logic when the command runs:

class MyPlugin {
  constructor() {
    this.commands = {
      'my-command': {
        lifecycleEvents: ['run'],
      },
    };

    this.hooks = {
      'my-command:run': () => {
        // Do something
      },
    };
  }
}

For each event, an additional before and after event is created:

this.hooks = {
  'before:my-command:run': () => {
    // Before my command runs
  },
  'my-command:run': () => {
    // My command runs
  },
  'after:my-command:run': () => {
    // After
  },
};

Note that a command can define multiple events: these will be called sequentially.

Command options

Commands can have CLI options:

• either passed with a double dash (--): serverless my-command --function functionName.
• or as a shortcut with a single dash (-): serverless my-command -f functionName.

Options can be specified in the command definition. The value of the CLI option can be retrieved via the options parameter of the plugin:

class MyPlugin {
  constructor(serverless, options) {
    this.options = options;

    this.commands = {
      'my-command': {
        // The 'usage' property is used to display the 'serverless --help' output
        usage: 'This is my new custom command!',
        lifecycleEvents: ['run'],
        options: {
          // Define the '--function' option with the '-f' shortcut
          function: {
            usage: 'Specify the function you want to handle (e.g. "--function myFunction")',
            shortcut: 'f',
            required: true,
            type: 'string', // Possible values: 'string', 'boolean', 'multiple'
          },
        },
      },
    };

    this.hooks = {
      'my-command:run': () => this.run(),
    };
  }

  run() {
    console.log('The option was: ', this.options.function);
  }
}

If an option is not required, a default property can be set in the option definition.

Command naming

Command names must be unique across all plugins. For example instead of defining a custom deploy command, name it my-company-deploy instead.

If a plugin defines a command name that conflicts with Serverless Framework core or another plugin, the CLI will exit with an error.