Usage

import { Command } from '@panda/command'

new Command({
  // required: name
  name: 'create-foo',
  // used as the command called when it's a subcommand
  command: 'foo:create',
  // used in help menu
  description: 'Create a new Foo',
  // application or command version
  version: '1.4.7',
  // argument handler
  //   if object, 'name' data key contains a single or multiple values
  //   if array, data keys are applied as positional arguments
  arguments: {
    name: 'name'
  },
  // list of options to parse
  options: [],
  // list of flags to parse
  flags: [],
  // list of subcommands
  //   if array, use the `command` property as the subcommand
  //   if object, use the key as the subcommand
  subcommands: [],
  // list of prompts to ask user
  prompts: [],
  // list of custom prompt types available to `prompts`
  promptTypes: {},
  // flag to automatically generate and display help menu on --help
  autoHelp: true,
  // flag to automatically output version on --version
  autoVersion: true,
  // flag to suppress logging output
  silent: false,
  // method to transform data before reaching action
  transform: async (data) => {
    data.type = 'based'
    return data
  },
  action: async (data, details) => {
    // perform your actions
  }
})

Properties

For a full list of properties, see the Command Properties documentation.

Methods

Process Methods

@panda/command provides a list of process methods that are used during the lifecycle of a command:

• initialize() prepares the command for execution
• run() runs the command
• prepare() converts passed properties into their usable instances
• parse() parses the command line arguments
• assemble() assembles the command line arguments
• runPrompts() runs the prompts
• transform() transforms the data before reaching the action
• action() processes the data

The only method that should be called directly is run(). The rest are called internally, but can be overwritten if needed.

Process Flow

• initialize()
  • prepare()
• run()
  • parse()
    • assemble()
  • runPrompts()
  • transform()
  • action()

Output Methods

@panda/command provides a list of output methods to use instead of/in addition to using console:

• style (styles) applies styles via an array (e.g. ['green', 'bold']) or string (e.g. green.bold)
• log (msg, opts) outputs the msg string and conditionally applies styling via opts
• out (msg, opts) similar to log()
• error (err, msg, exit) outputs an error, a custom message, and conditionally stops the script
• spacer () outputs an empty spacer row
• rainbow (text) returns the passed in text string as a rainbow
• heading (msg, opts) outputs a heading, which is bolded and contains spacers

const MyCommand = new Command({
  name: 'my-command',
  action: async function (data, details) {
    // will output a heading in bold with spacers
    this.heading('Example command output')
    // a simple output
    this.out('normal text')
    // text output bolded and in blue
    this.out('colorful text', { styles: ['blue', 'bold'] })
    // a spacer line in the console
    this.spacer()
    // outputs a line of text in rainbow
    this.out(this.rainbow('Rainbow sentence that goes on and on'))
    this.spacer()
    try {
      throw new Error('Example error')
    } catch (e) {
      // outputs an error and exits the console
      this.error(e, 'Example error message')
    }
  }
})

Built-in Functionality

Help Menu

By default, the --help option will output content showing the user how to use the command, its arguments and options, and give a list of subcommands.

new Command({
  name: 'my-command',
  argument: {
    name: 'name'
  },
  options: [{
    name: 'tags',
    alias: 't',
    type: 'string',
    multiple: true
  }],
  flags: [
    { name: 'verbose', alias: 'v' },
    { name: 'force', alias: 'f' }
  ],
  action: async function (data, details) {
    this.heading('Example Command')
    this.out({ data, details })
  }
})

$ node my-command.js --help

Usage: my-command [name] [OPTIONS]

Arguments:
  name                                   The name of the thing

Options:
  --tags, -t <tags...>                   The tags for the thing
  --verbose, -v                          Run in verbose mode
  --force, -f                            Force the action
  --help, -h                             Show help

Version Output

By default, the --version option will output the version of the command.

new Command({
  name: 'my-command',
  version: '1.0.0',
  action: async function (data, details) {
    this.heading('Example Command')
    this.out({ data, details })
  }
})

$ node my-command.js --version
1.0.0