@tkeron/commands

Zero-dependency CLI command parser and router for Bun/Node.js.

Install

bun add @tkeron/commands

Quick Start

import { getCommands } from "@tkeron/commands";

const cli = getCommands("myapp", "1.0.0")
  .addCommand("build")
  .addAlias("b")
  .addDescription("Build the project")
  .addFlag("verbose", "v", "Enable verbose output")
  .addStringOption("output", "o", "Output directory", { default: "./dist" })
  .addPositionedArgument("source")
  .setCallback(console.log)

  .commands()

  .addCommand("serve")
  .addAlias("s")
  .addDescription("Start dev server")
  .addNumberOption("port", "p", "Port number", { default: 3000 })
  .addFlag("open", "o", "Open browser")
  .setCallback(console.log)

  .commands()

  .addHeaderText("MyApp v1.0.0\n")
  .addFooterText("\nDocs: https://example.com");

cli.start();

Usage:

myapp build src --verbose -o dist
myapp serve -p 8080 --open
myapp help
myapp version

API

getCommands(programName, version)

Creates a new Commands instance.

Commands

| Method | Description | | ---------------------- | ------------------------------------------------- | | .addCommand(name) | Add a command, returns CommandFactory | | .addHeaderText(text) | Set help header text | | .addFooterText(text) | Set help footer text | | .start(argv?) | Parse and execute. Uses process.argv by default |

CommandFactory (chaining)

| Method | Description | | ----------------------------------------------------------- | ----------------------------------------- | | .addAlias(alias) | Add command alias | | .addDescription(text) | Set command description | | .addFlag(name, shortFlag?, description?) | Add boolean flag (--verbose, -v) | | .addStringOption(name, shortFlag?, description?, config?) | Add string option | | .addNumberOption(name, shortFlag?, description?, config?) | Add number option | | .addOption(name, example?) | Add legacy key=value option | | .addPositionedArgument(name) | Add positional argument | | .setCallback(fn) | Set command handler | | .commands() | Return to Commands to add more commands |

Option Config

addStringOption and addNumberOption accept an optional config object:

{
  default?: string | number | boolean;
  required?: boolean;
  aliases?: string[];
  allowedValues?: (string | number)[];
  valueName?: string;
}

Syntax Support

Both syntaxes work and can be mixed:

Standard (new):

myapp build --verbose --output dist
myapp build -v -o dist
myapp build -vw              # combined short flags
myapp build --no-verbose     # negated flags
myapp build -- --not-parsed  # stop parsing after --

Legacy (backward compatible):

myapp build output=dist format=json

Built-in Commands

help and version are added automatically.

License

MIT