cli-boilerplate

npm install @ferrow/cli-boilerplate

A small CLI micro-framework: a flag parser, subcommand router, auto-generated help text, ANSI color helpers, and levenshtein-based typo suggestions for unknown commands/flags. Zero runtime dependencies.

What this is

• A parseArgs(args, flagDefs) function supporting --key=value, --key value, combined short flags (-abc), --no-flag negation, typed flag definitions (string / number / boolean) with default and required.
• A CLI class for defining subcommands, each with its own flag schema and --help text generated from the definitions.
• colors — ANSI wrappers (red, green, bold, ...) that no-op when NO_COLOR is set.
• suggest(input, candidates) — levenshtein-based "did you mean" for unknown commands and unknown flags.
• Exit code convention: 0 success, 1 action threw, 2 usage error (unknown command/flag, missing required flag).

What this is NOT

• Not a prompts/interactive-input library.
• Not a config-file loader.
• Not a progress-bar or spinner library.
• Not a replacement for full-featured frameworks (commander, yargs, oclif) if you need plugin systems, shell completion, or i18n.

Quickstart

npm install
npm run build
node dist/examples/demo.js --help

API

import { CLI, parseArgs, colors, suggest } from 'cli-boilerplate';

const cli = new CLI({
  name: 'demo',
  version: '1.0.0',
  commands: {
    greet: {
      description: 'Greet someone',
      flags: {
        name: { type: 'string', default: 'World', alias: 'n' },
        loud: { type: 'boolean', default: false, alias: 'l' },
      },
      action: ({ flags }) => {
        console.log(flags.loud ? `HELLO, ${flags.name}!` : `Hello, ${flags.name}!`);
      },
    },
  },
});

cli.run(process.argv.slice(2)).then((code) => process.exitCode = code);

Running the bundled demo (examples/demo.ts, two commands: greet, add):

$ node dist/examples/demo.js --help
demo v1.0.0
...
Commands:
  greet         Greet someone
  add           Add two numbers

$ node dist/examples/demo.js greet --name=Chris -l
HELLO, CHRIS!

$ node dist/examples/demo.js greet --nam Chris
Unknown flag: --nam
Did you mean '--name'?

License

MIT

---

Sponsored by Ferrow

---

Part of the ferrow-toolkit collection · Sponsored by Ferrow