clipanion

library4.0.0-rc.4jsnpmunverified

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.

devops

npm install clipanion

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CLIPANION

clipanion

devopsjavascriptv4.0.0-rc.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Cli

✓ import { Cli } from 'clipanion'

✗ const { Cli } = require('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

✓ import { Command, Option } from 'clipanion'

✗ import Command 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

✓ import { Builtins } from 'clipanion'

✗ import { help, version } 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.

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); });

clipanion --version

Debug

Known issues

breakingClipanion 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.

affects: >=4.0.0-rc.0

gotchaClipanion 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.

affects: >=4.0.0-rc.0

gotchaThe `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.

affects: >=4.0.0-rc.0

gotchaClipanion 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.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: Command.String is not a function

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'

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

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.

Upgrade

Version history

4.0.0-rc.4latest on npm

Audit

Dependencies

typanionrequiredPeer dependency required for runtime type validation of command arguments and options. Clipanion uses typanion to derive runtime type checks from TypeScript static types.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/arcanis/clipanion ↗

packagehttps://www.npmjs.com/package/clipanion ↗

homepagehttps://mael.dev/clipanion/ ↗