commands-x
v0.0.1
Published
Elegant command-line interface (CLI) development tool
Downloads
13
Maintainers
Readme
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
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
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