Getting Started

Installation

npm install cli-kiss

Your first CLI

Example minimal "greet" CLI with:

• a required name positional argument
• optional --loud boolean flag

import {
  command,
  operation,
  optionFlag,
  positionalRequired,
  runAndExit,
  type,
} from "cli-kiss";

const greetCommand = command(
  { description: "Greet someone" },
  operation(
    {
      options: {
        loud: optionFlag({ long: "loud", description: "Print in uppercase" }),
      },
      positionals: [
        positionalRequired({
          type: type("name"),
          description: "The name of the person to greet",
        }),
      ],
    },
    async (_context, { options: { loud }, positionals: [name] }) => {
      const message = `Hello, ${name}!`;
      console.log(loud ? message.toUpperCase() : message);
    },
  ),
);

await runAndExit("greet", process.argv.slice(2), {}, greetCommand, {
  buildVersion: "1.0.0",
});

Run it:

greet Alice

Hello, Alice!

Pass a flag:

greet --loud Alice

HELLO, ALICE!

Help and color (built-in):

greet --help --color

Usage: greet <name>

Greet someone

Positionals:
  <name>  The name of the person to greet

Options:
  --loud[=no]  Print in uppercase

Version (built-in):

greet --version

greet 1.0.0

Project structure

A typical cli-kiss project looks like this:

my-cli/
├── src/
│   ├── index.ts        ← entry point: calls runAndExit
│   └── commands/
│       ├── deploy.ts   ← command(...) definitions
│       └── rollback.ts
└── package.json

Each command lives in its own file and is composed together in the entry point. See the Commands guide to learn how.