cac

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

github ↗package ↗homepage ↗

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.

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

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

import type { CAC } from 'cac'

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

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

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 footguns

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.

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

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.

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.

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.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

21 hits · last 30 days

bytedance

gptbot

ahrefsbot

script

googlebot

Resources

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

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

homepagehttps://cac.cnodejs.org ↗