@jiakun-zhao/cli

A lightweight CLI parsing library with full TypeScript type inference.

Features

• Command names can contain spaces (e.g. deploy production)
• Full type inference for action callbacks based on registered options
• Automatic --help and --version generation
• Zero runtime dependencies

Install

pnpm add @jiakun-zhao/cli

Usage

Basic

import { Program } from '@jiakun-zhao/cli'

const program = new Program({
  name: 'mycli',
  version: '1.0.0',
  description: 'A CLI tool',
})

program
  .command('deploy production', 'Deploy to production')
  .option('--host', 'Server host', String)
  .option('--port', 'Server port', Number)
  .option('--verbose', 'Verbose output', Boolean)
  .action((opts) => {
    // opts is typed as { host?: string; port?: number; verbose?: boolean }
    console.log(opts.host, opts.port, opts.verbose)
  })

program.parse(process.argv)

Option Name Format

Option names must follow --foo or --foo-bar format. Kebab-case names are automatically converted to camelCase in the action callback:

.option('--output-dir', 'Output directory', String)
.option('--max-retries', 'Max retries', Number)
.action((opts) => {
  console.log(opts.outputDir)  // not opts['output-dir']
  console.log(opts.maxRetries) // not opts['max-retries']
})

Pre-built Commands

You can also create a Command instance separately and register it:

import { Command, Program } from '@jiakun-zhao/cli'

const buildCmd = new Command('build', 'Build the project')
buildCmd
  .option('--minify', 'Minify output', Boolean)
  .option('--target', 'Build target', String)
  .action((opts) => {
    console.log(opts.minify, opts.target)
  })

const program = new Program({ name: 'mycli', version: '1.0.0', description: '...' })
program.command(buildCmd)

program.parse(process.argv)

Type Validation

Option names and types are validated at both compile time and runtime:

// Compile error: name must start with '--'
.option('host', 'Host', String)

// Compile error: type must be String, Number, or Boolean
.option('--host', 'Host', Array)

// Runtime error: invalid name format
.option('--Host', 'Host', String)      // must be lowercase
.option('--host name', 'Host', String) // no spaces allowed

Help Output

Running with --help or -h prints:

mycli - A CLI tool (v1.0.0)

Commands:
  deploy production   Deploy to production

Options:
  --help              Show help
  --version           Show version
  --host              Server host
  --port              Server port
  --verbose           Verbose output

Running with --version or -v prints:

mycli v1.0.0

API

new Program(config)

| Parameter | Type | Description | | -------------------- | -------- | ------------------- | | config.name | string | CLI program name | | config.version | string | Program version | | config.description | string | Program description |

program.command(name, description)

Register a command. Returns a Command instance for chaining.

program.command(cmd)

Register a pre-built Command instance.

command.option(name, description, type)

Register an option. Chainable.

| Parameter | Type | Description | | ------------- | ----------------------------- | -------------------------------------------------- | | name | `--${string}` | Option name, must be --foo or --foo-bar format | | description | string | Option description | | type | String \| Number \| Boolean | Value type |

command.action(handler)

Set the action handler. handler receives an object with parsed option values.

program.parse(argv)

Parse process.argv and execute the matched command's action. Returns a Promise.

License

MIT