cac

library1.0.0jsnpmunverified

CAC (Command And Conquer) is a lightweight, dependency-free JavaScript library for building robust command-line interface (CLI) applications. The current stable version, 7.0.0, released in 2024, marks a significant transition to being ESM-only and requires Node.js 20.19.0 or newer. CAC differentiates itself by providing a minimal API surface (four core methods for basic CLIs) while offering powerful features such as default commands, Git-like subcommands, argument and option validation, variadic arguments, and automated help message generation. Its development is TypeScript-first, ensuring type safety and an enhanced developer experience. Release cadence is typically feature-driven, with breaking changes carefully documented in major version bumps and minor/patch releases focusing on stability and compatibility.

devops

npm install cac

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CAC

cac

devopsjavascriptv1.0.0

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.

cac

✓ import cac from 'cac'

✗ const cac = require('cac')

Since v7.0.0, CAC is an ESM-only package. CommonJS `require()` is no longer supported directly. Use `import` statements or ensure your Node.js environment supports `require()` for ES modules natively (Node.js >= 20.19.0 with specific configurations).

CAC

✓ import type { CAC } from 'cac'

For TypeScript projects, you can import the `CAC` interface for type hinting of the CLI instance returned by the default `cac` factory function.

cli.addEventListener

✓ cli.addEventListener('command:name', () => {})

✗ cli.on('command:name', () => {})

As of v7.0.0, event listener methods have been renamed to align with the standard `EventTarget` API. `cli.on()` is no longer available.

This quickstart demonstrates how to initialize CAC, define options and commands, set a version, and enable automatic help message generation. It includes a basic error handling block for parsing issues.

import cac from 'cac' const cli = cac() cli.option('--type [type]', 'Choose a project type', { default: 'node', }) cli.option('--name <name>', 'Provide your name') cli.command('lint [...files]', 'Lint files').action((files, options) => { console.log(`Linting files: ${files.join(', ')} with options: ${JSON.stringify(options)}`) }) // Display help message when `-h` or `--help` appears cli.help() // Display version number when `-v` or `--version` appears cli.version('1.0.0') // Set your CLI's version try { cli.parse() } catch (error) { // Handle errors like unknown commands or options console.error(`CLI Error: ${error.message}`) process.exit(1) } // To run this: save as e.g. cli.mjs and execute with `node cli.mjs --help` or `node cli.mjs lint src/*.js`

Debug

Known issues

breakingCAC v7.0.0 and above now requires Node.js 20.19.0 or a higher version. Running on older Node.js versions will result in runtime errors.

fix

Upgrade your Node.js environment to version 20.19.0 or higher. Use a version manager like `nvm` to easily switch Node.js versions (e.g., `nvm install 20 && nvm use 20`).

affects: >=7.0.0

breakingCAC is now an ESM-only package since v7.0.0. The CommonJS (CJS) build has been removed, meaning `require()` statements will no longer work directly for importing `cac`.

fix

Migrate your project to use ES module `import` syntax (e.g., `import cac from 'cac'`). Ensure your `package.json` specifies `"type": "module"` or use `.mjs` file extensions. For mixed environments, consider dynamic `import()` or transpilation.

affects: >=7.0.0

breakingThe event listener methods `cli.on()`, `cli.once()`, and `cli.off()` have been renamed to `cli.addEventListener()`, `cli.addOnceListener()`, and `cli.removeEventListener()`, respectively, to align with the standard `EventTarget` API.

fix

Update all calls to these event methods in your codebase to use the new `addEventListener`-like naming conventions.

affects: >=7.0.0

gotchaCAC automatically converts kebab-case option names (e.g., `--clear-screen`) to camelCase (e.g., `options.clearScreen`) in the parsed options object. Be consistent in how you access these options.

fix

When defining options with kebab-case, always access them in your action functions using their camelCase equivalent.

affects: >=1.0.0

gotchaCommand-specific options are validated only if an `action` function is defined for that command. If a command has options but no `action`, unknown options will not trigger a validation error unless `command.allowUnknownOptions()` is explicitly set.

fix

Always define an `.action()` for commands that have options if you require strict validation. If intentionally allowing unknown options, use `command.allowUnknownOptions()`.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/cac/dist/index.mjs from .../your-script.js not supported.

Attempting to use `require('cac')` in a CommonJS context after v7.0.0 when CAC is an ESM-only package.

fix

Convert your script to an ES module by using `import cac from 'cac'` and ensuring your project's `package.json` has `"type": "module"` or your file has a `.mjs` extension.

TypeError: cli.on is not a function

Using the deprecated `cli.on()` method after upgrading to CAC v7.0.0 or later.

fix

Rename `cli.on()` to `cli.addEventListener()` everywhere in your code. Similarly, replace `cli.once()` with `cli.addOnceListener()` and `cli.off()` with `cli.removeEventListener()`.

Error: Node.js version 18.x.x is not supported by CAC. Minimum required version is 20.19.0.

Running a CAC v7.0.0+ application on an unsupported Node.js version.

fix

Update your Node.js environment to version 20.19.0 or higher. You can use tools like `nvm use 20` or `volta install node@20`.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

26 hits · last 30 days

node

Resources

githubhttps://github.com/cacjs/cac ↗

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

homepagehttps://cac.cnodejs.org ↗