npm package: @jiakun-zhao/cli
Description: A lightweight CLI parsing library with full TypeScript type inference. Generated by AI.
Author: Jiakun Zhao
Latest version: 0.0.1

# @jiakun-zhao/cli

![NPM Version](https://img.shields.io/npm/v/@jiakun-zhao/cli?labelColor=%23000&color=%23954)
![NPM Version](https://img.shields.io/npm/l/@jiakun-zhao/cli?labelColor=%23000&color=%23954)

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

```bash
pnpm add @jiakun-zhao/cli
```

## Usage

### Basic

```ts
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:

```ts
.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:

```ts
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:

```ts
// 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