Type-Safe CLI Framework

Common errors

• TypeError: Command.String is not a function

  cause This error typically occurs when trying to use `Command.String()` for option validation in Clipanion v3, or when `typanion` is not correctly integrated/installed in v4.
  fix For Clipanion v4, ensure `typanion` is installed (`npm i typanion`) and that you're correctly using `Option.String('--name', { validator: Command.String() })`. For Clipanion v3, argument validation was handled differently and `Command.String()` was not part of the public API for options.

• Error: Cannot find module 'clipanion' or 'clipanion/package.json'

  cause This usually indicates a module resolution issue, most commonly when a CommonJS project tries to import an ESM-only package, or when the package is not installed.
  fix First, ensure `clipanion` is installed (`npm i clipanion`). If it is, configure your `package.json` with `"type": "module"` for ESM, or ensure your build system transpiles ESM imports to CommonJS correctly if you must remain in a CJS environment.

• ReferenceError: require is not defined

  cause This error occurs when you're using a `require()` statement in an ES Module context, or when running an ES Module file directly with Node.js without the `--experimental-json-modules` flag for JSON or other non-JS imports.
  fix Replace `require()` calls with `import` statements. Ensure your project's `package.json` has `"type": "module"` or that the file explicitly uses the `.mjs` extension for ES Module interpretation.

Warnings

• breaking Clipanion v4 introduces significant breaking changes from v3, primarily around option and argument definition. The `Command.String()`, `Command.Boolean()`, etc., now explicitly leverage `typanion` validators, which replaces the older, less type-safe methods of defining options. Direct access to `this.args` for positional arguments might also be altered in favor of explicit `Option.Rest()` or `Option.Array()` definitions.
  Fix: Review the v4 migration guide (when available) and adapt command definitions to use the new `Option` and `Command.<Type>()` fluent API for validators. Ensure `typanion` is correctly installed as a peer dependency.
• gotcha Clipanion v4 is designed with an ESM-first approach. Attempting to use `require()` for imports in a CommonJS context without proper transpilation or configuration will lead to module resolution errors. Projects should generally be configured for ESM (`"type": "module"` in `package.json`).
  Fix: Configure your project to use ES Modules by adding `"type": "module"` to your `package.json` and using `import` statements. If a CJS environment is strictly required, ensure your build pipeline (e.g., Babel, TypeScript compiler) correctly transpiles ESM to CJS, or consider sticking to Clipanion v3 if CJS compatibility is paramount.
• gotcha The `typanion` peer dependency is crucial for Clipanion v4's core functionality, especially for runtime argument validation. Forgetting to install `typanion` or having a mismatch in versions can lead to runtime errors or unexpected parsing behavior.
  Fix: Always install `typanion` alongside `clipanion`: `npm install typanion` or `yarn add typanion`. Ensure the installed version is compatible with your Clipanion version, generally matching the `*` peer dependency requirement.
• gotcha Clipanion provides `Builtins.HelpCommand` and `Builtins.VersionCommand` for standard CLI functionality. Developers new to Clipanion sometimes overlook registering these, leading to CLIs without a `--help` or `--version` option, which is a common user expectation.
  Fix: Ensure you register the built-in commands: `cli.register(Builtins.HelpCommand); cli.register(Builtins.VersionCommand);`. Consider adding `Builtins.DefinitionsCommand` as well for advanced introspection.

Install

• npm install clipanion npm
• yarn add clipanion yarn
• pnpm add clipanion pnpm

Imports

• Cli
  wrong:

  const { Cli } = require('clipanion')

  correct:

  import { Cli } from 'clipanion'

  Clipanion v4 is designed primarily for ESM. While CJS might work via transpilation, direct `require` is not the recommended or idiomatic approach. Use named imports from the main package entry point.
• Command
  wrong:

  import Command from 'clipanion'

  correct:

  import { Command, Option } from 'clipanion'

  Command is a named export, not a default export. `Option` is also a named export, used for defining command arguments and options.
• Builtins
  wrong:

  import { help, version } from 'clipanion'

  correct:

  import { Builtins } from 'clipanion'

  Common built-in commands like `help` and `version` are exposed as properties of the `Builtins` object. Add `...Builtins.Entries` to your CLI to include them.

Quickstart

This quickstart demonstrates a basic Clipanion CLI with a 'hello' command, utilizing `Option.String` for argument parsing with a default value and integrating built-in help and version commands. It showcases the ESM-first approach and the use of `Command.String()` for validation.

import { Cli, Command, Option, Builtins } from 'clipanion';
import process from 'node:process';

class HelloCommand extends Command {
  static paths = [['hello'], ['hi']];

  name = Option.String('--name', { 
    description: 'Name to greet',
    required: false,
    validator: Command.String().withDefault('World')
  });

  async execute() {
    this.context.stdout.write(`Hello, ${this.name}!\n`);
  }
}

async function main() {
  const cli = new Cli({
    binaryLabel: `My CLI App`,
    binaryName: `my-cli`,
    binaryVersion: `1.0.0`,
  });

  cli.register(HelloCommand);
  cli.register(Builtins.VersionCommand);
  cli.register(Builtins.HelpCommand);
  
  await cli.run(process.argv.slice(2), { 
    cwd: process.cwd(),
    stdout: process.stdout,
    stdin: process.stdin,
    stderr: process.stderr,
    env: process.env,
  });
}

main().catch(err => {
  console.error('CLI Error:', err);
  process.exit(1);
});