CAC CLI Framework

Common errors

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

  cause 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

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

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

Warnings

• breaking 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.
  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`).
• breaking 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`.
  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.
• breaking 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.
  Fix: Update all calls to these event methods in your codebase to use the new `addEventListener`-like naming conventions.
• gotcha 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.
  Fix: When defining options with kebab-case, always access them in your action functions using their camelCase equivalent.
• gotcha 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.
  Fix: Always define an `.action()` for commands that have options if you require strict validation. If intentionally allowing unknown options, use `command.allowUnknownOptions()`.

Install

• npm install cac npm
• yarn add cac yarn
• pnpm add cac pnpm

Imports

• cac
  wrong:

  const cac = require('cac')

  correct:

  import cac from '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
  wrong:

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

  correct:

  cli.addEventListener('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.

Quickstart

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`