go-plugin-cli

Go plugin to create and execute commmands.

This plugin is made on top of Liftoff. Thanks @jonschlinkert, @phated, tkellen and tusbar for it!

Table of Contents

• go-plugin-cli
  • Table of Contents
  • Usage
    • Installation
    • Quick Start
  • Api
    • Methods
      • registerCommand
      • matchCommand
      • executeCommand
      • getCommands
    • CLI
    • Command
      • name
      • callback
      • commands
      • description
      • title
      • prefix
      • when
      • options
    • Parsed Command
    • Parsing Command Options
  • Examples
  • License

Usage

Installation

$ npm install --save-dev go go-plugin-cli

import go from 'go'
import { CliPlugin } from 'go-plugin-cli'
go.use(CliPlugin)

Quick Start

Cli Plugin helps you to create command-line interface for your boilerplate and commands. You can easily create interactive menus for your app when using it in pair with Go CLI. For example, you may want to provide install command in CLI:

// gofile.js in root directory of your application
import go from 'go'
import { CliPlugin } from 'go-plugin-cli'
go.use(CliPlugin)
 
go.registerCommand('greet', async () => {
  console.log('Welcome!')
})

$ go greet
Welcome!

Api

Methods

registerCommand

go.registerCommand( commands [ , callback ] ): void

• commands {string|object|array} — can be a string that will result in a name of a command, an object with command options or an array of mixed string and objects
• callback {function} — becomes a callback for a command when commands is a string

Registers new command to the list.

matchCommand

go.matchCommand( commandString ): Command

• commandString {string} — a string with the name of command and flags

Find a registered command.

executeCommand

go.executeCommand( commandString ): Promise<any>

• commandString {string} — a string with the name of command and flags

Find and execute registered command.

getCommands

go.getCommands(): Command[]

Returns a RAW list of registered commands.

CLI

$ go # to run interactive menu 
$ go command with flags # to run the registered command 

Command

Command is an object with options. Here is the list of possible options:

name

• Required
• Valid types: string

The name of the command that will be used to trigger it.

callback

• Required (if commands are not provided)
• Valid types: function
• Function arguments: object (parsed command)

The callback function will be called when command is triggered.

commands

• Required (if callback is not provided)
• Valid types: array (a list of commands)

Nested commands can be triggered by using their name after the name of parent command, or from interactive menu.

description

• Valid types: string

The description of the command that will be shown in the interactive menu.

title

• Valid types: string
• Default value: "Choose command:"

The title will be shown in interactive menu for nested commands.

prefix

• Valid types: string
• Default value: "GO"

The prefix will be shown in interactive menu for nested commands.

when

• Valid types: string|array|object|function
• Function arguments: object (parsed command)

Adds additional check when matching command. This lets you use the same command name and trigger different commands depending on flags or environment.

If when is specified as a string it will match the command only if specified flag has truthy value. when can also be specified as an array of string's. Then the precense of each mentioned flag will be validated. To check the specific value of the flag when can be given as an object in a format { flagName: flagValue }.

For more control function can be used as when option. It should return either truthy or falsy value and that will determine if command is matching or not.

options

• Valid types: object

The configuration object for parsing command. When used in nested command it iherits options from parent commands. Read parsing command options section to learn more about it.

Parsed Command

Command callbacks receive parsed CLI command as an argument. The structure of an object:

• args {object} — parsed command
  • _ {array} — the list of command partials (strings)
  • [flag name] {boolean|string} — values of each given flag
  • -- {array} — the list of strings given after -- sign

Parsing Command Options

There is an option to configure how command will be parsed. This is an object that can be written in 2 ways: { flagName: type } or { flagName: options }

List of options:

• type {Boolean|String} — defines how flag should be parsed
• alias {string|array} — alias string or an array of alias strings
• default {any} — default value when flag is not used

Examples

License

MIT © Stanislav Termosa