clipanion typed CLI parser: working versions (tested 2026-10-16)

{
  "name": "clipanion-cli-parser",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --import tsx --test test/*.test.ts"
  },
  "dependencies": {
    "clipanion": "3.2.1"
  },
  "devDependencies": {
    "@types/node": "26.6.5",
    "tsx": "4.23.15"
  }
}

import { Builtins, Cli, Command, Option } from "clipanion";

export class AddCommand extends Command {
  static paths = [["add"]];

  static usage = Command.Usage({
    category: "Math",
    description: "Add two integers together.",
    examples: [["Add 1 and 2", "$0 add --a 1 --b 2"]],
  });

  a = Option.String("--a", { required: true });
  b = Option.String("--b", { required: true });
  verbose = Option.Boolean("-v,--verbose", false);

  async execute(): Promise<number> {
    const left = Number(this.a);
    const right = Number(this.b);

    if (Number.isNaN(left) || Number.isNaN(right)) {
      this.context.stderr.write("error: --a and --b must be numbers\n");
      return 1;
    }

    if (this.verbose) {
      this.context.stderr.write(`verbose: ${left} + ${right}\n`);
    }

    this.context.stdout.write(`${left + right}\n`);
    return 0;
  }
}

export class GreetCommand extends Command {
  static paths = [["greet"]];

  static usage = Command.Usage({
    category: "Text",
    description: "Greet someone by name.",
    examples: [["Greet Ada", "$0 greet --name ada --shout"]],
  });

  name = Option.String("--name");
  shout = Option.Boolean("--shout", false);

  async execute(): Promise<number> {
    const message = `Hello, ${this.name ?? "world"}`;
    this.context.stdout.write(`${this.shout ? message.toUpperCase() : message}\n`);
    return 0;
  }
}

export function createCli(): Cli {
  const cli = new Cli({
    binaryLabel: "demo",
    binaryName: "demo",
    binaryVersion: "1.0.0",
  });

  cli.register(Builtins.HelpCommand);
  cli.register(Builtins.VersionCommand);
  cli.register(AddCommand);
  cli.register(GreetCommand);

  return cli;
}

import { test } from "node:test";
import assert from "node:assert/strict";
import { Writable } from "node:stream";
import { Cli } from "clipanion";
import { createCli } from "../src/cli.ts";

function capture() {
  let output = "";
  const stream = new Writable({
    write(chunk, _encoding, callback) {
      output += chunk.toString();
      callback();
    },
  });

  return {
    stream,
    get output() {
      return output;
    },
  };
}

function makeContext() {
  const stdout = capture();
  const stderr = capture();

  return {
    stdout,
    stderr,
    context: {
      ...Cli.defaultContext,
      stdout: stdout.stream,
      stderr: stderr.stream,
    },
  };
}

test("runs the add command and exits 0", async () => {
  const cli = createCli();
  const { context, stdout } = makeContext();

  const code = await cli.run(["add", "--a", "1", "--b", "2"], context);

  assert.equal(code, 0);
  assert.equal(stdout.output, "3\n");
});

test("supports boolean flags", async () => {
  const cli = createCli();
  const { context, stdout, stderr } = makeContext();

  const code = await cli.run(["add", "--a", "2", "--b", "3", "--verbose"], context);

  assert.equal(code, 0);
  assert.equal(stdout.output, "5\n");
  assert.equal(stderr.output, "verbose: 2 + 3\n");
});

test("greet falls back to its default name", async () => {
  const cli = createCli();
  const { context, stdout } = makeContext();

  const code = await cli.run(["greet"], context);

  assert.equal(code, 0);
  assert.equal(stdout.output, "Hello, world\n");
});

test("greet honours --shout", async () => {
  const cli = createCli();
  const { context, stdout } = makeContext();

  const code = await cli.run(["greet", "--name", "ada", "--shout"], context);

  assert.equal(code, 0);
  assert.equal(stdout.output, "HELLO, ADA\n");
});

test("prints command help and exits 0", async () => {
  const cli = createCli();
  const { context, stdout } = makeContext();

  const code = await cli.run(["add", "--help"], context);

  assert.equal(code, 0);
  assert.match(stdout.output, /Usage/);
  assert.match(stdout.output, /--a/);
  assert.match(stdout.output, /--b/);
});

test("prints top-level help listing commands", async () => {
  const cli = createCli();
  const { context, stdout } = makeContext();

  const code = await cli.run(["--help"], context);

  assert.equal(code, 0);
  assert.match(stdout.output, /add/);
  assert.match(stdout.output, /greet/);
});

test("returns exit code 1 for a usage error", async () => {
  const cli = createCli();
  const { context, stdout, stderr } = makeContext();

  const code = await cli.run(["add", "--a", "1"], context);

  assert.equal(code, 1);
  assert.match(stdout.output + stderr.output, /--b/);
});

test("returns exit code 1 for an unknown command", async () => {
  const cli = createCli();
  const { context } = makeContext();

  const code = await cli.run(["nope"], context);

  assert.equal(code, 1);
});

test("prints the binary version", async () => {
  const cli = createCli();
  const { context, stdout } = makeContext();

  const code = await cli.run(["--version"], context);

  assert.equal(code, 0);
  assert.match(stdout.output, /1\.0\.0/);
});