# cli

<p>
  <a href="https://www.npmjs.com/package/@cirrusct/cli">
    <img src="https://img.shields.io/npm/v/@cirrusct/cli.svg" alt="npm version">
  </a>
</p>

Feature-rich, data-driven Node JS Command Line Interface (CLI) tool.

## Installation

```
$ yarn add @cirrusct/cli
or
$ npm install @cirrusct/cli
```

## Usage

```typescript
import { Cli, CliProgramDefinition, CliRunResult } from '@cirrusct/cli';

// Define command(s)
const command: CliCommandDefinition = {
    // command name
    name: 'serve',
    description: 'Start Web Server',
    // handler called when command is executed 
    handler: parsed => {
        console.log(`Running command: ${parsed.parsedCommandName}`)
    },
    // define positional arguments
    arguments: [
        {
            name: 'arg1',
            description: 'First positional argument'
        }
    ],
    // define options (specified with '--[name]' or '-[flag]')
    options: [
        {
            name: 'logLevel',
            flag: 'l',
            description: 'Output message log level',
        },
    ],
};

// Define program containing array of commands
const cliProgram: CliProgramDefinition = {
    commands: [command],
    description: 'Server',
    name: 'server',
};

// Start Cli to parse command line and call command handler based on Cli input
export const start = async (): Promise<CliRunResult> => {
    return Cli.start(cliProgram)
};

```



## API

### Command Definition
The `CliCommandDefinition` interface defines a command to be parsed from CLI input and has the following properties:

| Property                       | Type                                   | Description                                                  |
| ------------------------------ | -------------------------------------- | ------------------------------------------------------------ |
| name                           | string                                 | Command Name                                                 |
| description                    | string                                 | Command description                                          |
| arguments                      | Array (`CliCommandDefinitionArgument`) | Command Arguments                                            |
| options                        | Array (`CliCommandDefinitionOption`)   | Command Options                                              |
| allowDynamicOptions (Optional) | Boolean                                | Allow options to be specified on command line that are not defined as part of the definition |
| examples                       | string array                           | Usage Examples                                               |
| transformOptions               | (options) => Options                   | Function to transform options                                |
| handler                        | `CommandHandler`                       | Function called when command is executed                     |
| env (Optional)                 | Hash                                   | Environment                                                  |
| transformArguments             | (arguments) => Arguments               | Function to transform arguments                              |