Roar

A simple CLI framework for building command-line tools with meow.

Roar provides a lightweight, type-safe way to build CLI applications with subcommands, typed flags, and auto-generated help text.

Install

npm install @d-dev/roar

Usage

Basic command

import { createCommand } from "@d-dev/roar";

const cli = createCommand(
  {
    usageName: "greet",
    version: "1.0.0",
    description: "A friendly greeter",
    versionFlag: ["version", "v"],
    helpFlag: ["help", "h"],
    flags: {
      name: {
        type: "string",
        description: "Name to greet",
        shortFlag: "n",
      },
      loud: {
        type: "boolean",
        description: "Greet loudly",
        default: false,
      },
    },
  },
  async (result) => {
    const greeting = `Hello, ${result.flags.name || "world"}!`;
    console.log(result.flags.loud ? greeting.toUpperCase() : greeting);
  },
);

await cli.run(process.argv.slice(2));

$ greet --name Ada
Hello, Ada!

$ greet --name Ada --loud
HELLO, ADA!

$ greet --help
Usage
  greet [options]

Options
  --name, -n        Name to greet
  --loud            Greet loudly
  --version, -v     Show version number
  --help, -h        Show help

Subcommands

import { createCommand } from "@d-dev/roar";

const add = createCommand(
  {
    description: "Add a new item",
    flags: {
      name: {
        type: "string",
        description: "Item name",
        isRequired: true,
      },
    },
  },
  async (result) => {
    console.log(`Added: ${result.flags.name}`);
  },
);

const list = createCommand(
  {
    description: "List all items",
    flags: {
      json: {
        type: "boolean",
        description: "Output as JSON",
        default: false,
      },
    },
  },
  async (result) => {
    console.log("Listing items...");
  },
);

const cli = createCommand({
  usageName: "items",
  version: "1.0.0",
  description: "Manage items",
  versionFlag: ["version", "v"],
  helpFlag: ["help", "h"],
});

cli.addCommand("add", add);
cli.addCommand("list", list);

await cli.run(process.argv.slice(2));

$ items --help
Usage
  items <command> [options]

Commands
  add         Add a new item
  list        List all items

Options
  --version, -v     Show version number
  --help, -h        Show help

Reading values from package.json

You can read the version and description fields from your package.json at runtime using Node.js APIs. This is useful to keep your CLI metadata in sync with your package metadata.

Example

import { readFileSync } from "node:fs";
import { resolve } from "node:path";

const pkg = JSON.parse(
  readFileSync(resolve(import.meta.dirname, "../package.json"), "utf8"),
);

const cli = createCommand(
  {
    usageName: pkg.name,
    version: pkg.version,
    description: pkg.description,
    // ...other options
  },
  async (result) => {
    // ...handler code
  },
);

This approach ensures your CLI always reports the correct version and description from your package.json.

API

createCommand(options, handler?)

Creates a new command and returns a Command object.

options

| Option | Type | Description | | ------------- | ---------------------------- | ---------------------------------------------------- | | usageName | string | Name displayed in usage text | | version | string | Version string shown with --version | | description | string | Description of the command | | flags | Flags | Flag definitions (see below) | | versionFlag | string \| [string, string] | Name (and optional short alias) for the version flag | | helpFlag | string \| [string, string] | Name (and optional short alias) for the help flag |

handler

(result: ParseResult<F>) => Promise<void>;

An async function that receives the parsed CLI result from meow. The result contains:

• result.input — Non-flag arguments
• result.flags — Parsed flags (fully typed based on your flag definitions)

Flags

Each flag is an object with:

| Property | Type | Description | | ------------- | ----------------------------------- | -------------------------------------------- | | type | 'string' \| 'boolean' \| 'number' | The type of the flag value | | description | string | Description shown in help text | | shortFlag | string | Single-character alias (e.g. 'n' for -n) | | default | varies | Default value | | isRequired | boolean | Whether the flag is required | | isMultiple | boolean | Accept multiple values (results in an array) |

command.addCommand(name, command)

Registers a subcommand.

command.run(args)

Parses args and runs the command (or matching subcommand).

License

MIT © Derek Worthen