{"id":10604,"library":"cac","title":"CAC CLI Framework","description":"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.","status":"active","version":"7.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/cacjs/cac","tags":["javascript"],"install":[{"cmd":"npm install cac","lang":"bash","label":"npm"},{"cmd":"yarn add cac","lang":"bash","label":"yarn"},{"cmd":"pnpm add cac","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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).","wrong":"const cac = require('cac')","symbol":"cac","correct":"import cac from 'cac'"},{"note":"For TypeScript projects, you can import the `CAC` interface for type hinting of the CLI instance returned by the default `cac` factory function.","symbol":"CAC","correct":"import type { CAC } from 'cac'"},{"note":"As of v7.0.0, event listener methods have been renamed to align with the standard `EventTarget` API. `cli.on()` is no longer available.","wrong":"cli.on('command:name', () => {})","symbol":"cli.addEventListener","correct":"cli.addEventListener('command:name', () => {})"}],"quickstart":{"code":"import cac from 'cac'\n\nconst cli = cac()\n\ncli.option('--type [type]', 'Choose a project type', {\n  default: 'node',\n})\ncli.option('--name <name>', 'Provide your name')\n\ncli.command('lint [...files]', 'Lint files').action((files, options) => {\n  console.log(`Linting files: ${files.join(', ')} with options: ${JSON.stringify(options)}`)\n})\n\n// Display help message when `-h` or `--help` appears\ncli.help()\n// Display version number when `-v` or `--version` appears\ncli.version('1.0.0') // Set your CLI's version\n\ntry {\n  cli.parse()\n} catch (error) {\n  // Handle errors like unknown commands or options\n  console.error(`CLI Error: ${error.message}`)\n  process.exit(1)\n}\n\n// To run this: save as e.g. cli.mjs and execute with `node cli.mjs --help` or `node cli.mjs lint src/*.js`","lang":"typescript","description":"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."},"warnings":[{"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`).","message":"CAC 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.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"CAC 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`.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Update all calls to these event methods in your codebase to use the new `addEventListener`-like naming conventions.","message":"The 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.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"When defining options with kebab-case, always access them in your action functions using their camelCase equivalent.","message":"CAC 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always define an `.action()` for commands that have options if you require strict validation. If intentionally allowing unknown options, use `command.allowUnknownOptions()`.","message":"Command-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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `require('cac')` in a CommonJS context after v7.0.0 when CAC is an ESM-only package.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/cac/dist/index.mjs from .../your-script.js not supported."},{"fix":"Rename `cli.on()` to `cli.addEventListener()` everywhere in your code. Similarly, replace `cli.once()` with `cli.addOnceListener()` and `cli.off()` with `cli.removeEventListener()`.","cause":"Using the deprecated `cli.on()` method after upgrading to CAC v7.0.0 or later.","error":"TypeError: cli.on is not a function"},{"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`.","cause":"Running a CAC v7.0.0+ application on an unsupported Node.js version.","error":"Error: Node.js version 18.x.x is not supported by CAC. Minimum required version is 20.19.0."}],"ecosystem":"npm"}