Commands-X

English | 简体中文

Elegant command-line interface (CLI) development tool, providing a set of features and utilities to simplify the process of creating command-line applications

Features

• Zero dependencies
• Sub-commands support
• Strongly typed arguments
• Auto generated usage and version
• Fast and lightweight arguments parser

Playground

You can try it out online in a live demo environment:

Live Demo

Install

npm install commands-x --save-dev

Quick Start

The simplest way to create a CLI application:

Create a file: simple.ts

import { runCommand } from 'commands-x'

runCommand({
  meta: {
    name: 'simple',
    version: '0.0.1',
    description: 'simple description...'
  },
  args: {
    firstName: {
      type: 'positional',
      description: 'Your first name',
      isRequired: true
    },
    lastName: {
      type: 'positional',
      description: 'Your last name'
    },
    nickName: {
      type: 'string',
      description: 'Your nick name',
      alias: 'n'
    },
    age: {
      type: 'number',
      description: 'Your age',
      alias: 'a'
    },
    isDeveloper: {
      type: 'boolean',
      description: 'You are developer or not?',
      alias: 'd',
      defaultValue: false
    }
  },
  main: (context) => {
    //
    // In development, type hints are provided
    //
    // context: {
    //   // Parsed command-line input arguments
    //   argv: {
    //     end: string[],
    //     unknown: Record<string, boolean | number | string>,
    //     positional: string[]
    //   }
    //   // Parsed user-defined arguments
    //   args: {
    //     firstName: string
    //     lastName: string | undefined
    //     nickName: string | undefined
    //     age: number | undefined
    //     isDeveloper: boolean
    //   }
    // }
    //
    console.log(context)
  }
})

Run the script to see it in action:

$ tsx examples/simple John Doe -n John -a 26 -d

{
  argv: { end: [], unknown: {}, positional: [] },
  args: {
    nickName: 'John',
    age: 26,
    isDeveloper: true,
    firstName: 'John',
    lastName: 'Doe'
  }
}

By default, errors are captured, formatted, and printed to the console:

$ tsx examples/simple

Error: Missing required argument: first-name
  at parse (src/parser.ts:169:17)
  at matchCommand (src/command.ts:35:31)
  at runCommand (src/command.ts:114:28)

By default, --help or -h is used to show usage:

$ tsx examples/simple -h

simple v0.0.1 - simple description...

USAGE

  simple [options] <first-name> [last-name]

ARGUMENTS

  first-name          (required)        Your first name
  last-name                             Your last name

OPTIONS

  -n, --nick-name                       Your nick name
  -a, --age                             Your age
  -d, --is-developer  (default: false)  You are developer or not?

By default, --version or -v is used to show version:

$ tsx examples/simple -v
v0.0.1

You can control the above default behavior by passing configuration parameters.

If you want to disable:

runCommand(
  {
    ...
  },
  {
    handleError: false,
    handleUsage: false,
    handleVersion: false
  }
)

If you want to customize handling:

runCommand(
  {
    ...
  },
  {
    handleError: (error) => { ... },
    handleUsage: (command, { argv }) => { ... },
    handleVersion: (command, { argv }) => { ... }
  }
)

Examples

• simple
• sub-commands
• only-parsing

Utils

defineCommand

A type helper for defining commands.

matchCommand

Matches commands and return an array containing matched command objects and parsed command-line input arguments objects. The first element is the main-command, and the second element is the selected sub-command.

runCommand

Runs commands with auto generated usage/version help and graceful error handling by default.

showVersion

Generates version and prints to the console.

showUsage

Generates usage and prints to the console.

parse

Parses command-line input arguments and convert them into an easily usable data structure based on user-defined arguments specifications.

License

MIT License © 2023-PRESENT 13OnTheCode