{"id":10640,"library":"clipanion","title":"Type-Safe CLI Framework","description":"Clipanion is a TypeScript-first framework for building robust and type-safe command-line interfaces (CLIs). It leverages TypeScript's powerful type system to define command arguments and options, providing compile-time validation and autocompletion, significantly reducing common runtime errors associated with CLI parsing. The package is currently at version `4.0.0-rc.4`, indicating active development towards a stable major release with a strong emphasis on modern JavaScript and TypeScript practices. A key differentiator is its zero runtime dependencies (beyond its peer dependency `typanion` for runtime type validation), resulting in extremely small bundle sizes. It integrates deeply with `typanion` to derive runtime validators directly from static TypeScript types, providing a seamless development experience for complex CLI applications. This approach contrasts with other CLI libraries that often rely on separate schema definitions or less integrated type checking.","status":"active","version":"4.0.0-rc.4","language":"javascript","source_language":"en","source_url":"https://github.com/arcanis/clipanion","tags":["javascript","cli","typescript","parser","parsing","argument","args","option","command"],"install":[{"cmd":"npm install clipanion","lang":"bash","label":"npm"},{"cmd":"yarn add clipanion","lang":"bash","label":"yarn"},{"cmd":"pnpm add clipanion","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for runtime type validation of command arguments and options. Clipanion uses typanion to derive runtime type checks from TypeScript static types.","package":"typanion","optional":false}],"imports":[{"note":"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.","wrong":"const { Cli } = require('clipanion')","symbol":"Cli","correct":"import { Cli } from 'clipanion'"},{"note":"Command is a named export, not a default export. `Option` is also a named export, used for defining command arguments and options.","wrong":"import Command from 'clipanion'","symbol":"Command","correct":"import { Command, Option } from 'clipanion'"},{"note":"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.","wrong":"import { help, version } from 'clipanion'","symbol":"Builtins","correct":"import { Builtins } from 'clipanion'"}],"quickstart":{"code":"import { Cli, Command, Option, Builtins } from 'clipanion';\nimport process from 'node:process';\n\nclass HelloCommand extends Command {\n  static paths = [['hello'], ['hi']];\n\n  name = Option.String('--name', { \n    description: 'Name to greet',\n    required: false,\n    validator: Command.String().withDefault('World')\n  });\n\n  async execute() {\n    this.context.stdout.write(`Hello, ${this.name}!\\n`);\n  }\n}\n\nasync function main() {\n  const cli = new Cli({\n    binaryLabel: `My CLI App`,\n    binaryName: `my-cli`,\n    binaryVersion: `1.0.0`,\n  });\n\n  cli.register(HelloCommand);\n  cli.register(Builtins.VersionCommand);\n  cli.register(Builtins.HelpCommand);\n  \n  await cli.run(process.argv.slice(2), { \n    cwd: process.cwd(),\n    stdout: process.stdout,\n    stdin: process.stdin,\n    stderr: process.stderr,\n    env: process.env,\n  });\n}\n\nmain().catch(err => {\n  console.error('CLI Error:', err);\n  process.exit(1);\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0-rc.0"},{"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.","message":"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`).","severity":"gotcha","affected_versions":">=4.0.0-rc.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0-rc.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: Command.String is not a function"},{"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.","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.","error":"Error: Cannot find module 'clipanion' or 'clipanion/package.json'"},{"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.","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.","error":"ReferenceError: require is not defined"}],"ecosystem":"npm"}