{"id":15092,"library":"caporal","title":"Caporal CLI Framework","description":"Caporal is a comprehensive framework for building command-line interface (CLI) applications with Node.js. It offers robust features for defining commands, parsing arguments, and handling options, along with automated help generation, colorful output, adjustable verbosity, and custom logging. Distinguishing features include built-in type coercion (e.g., `prog.INT`), intelligent typo suggestions for commands, and shell auto-completion capabilities for Bash, Zsh, and Fish. The current stable version is 3.1.5, released in August 2023, succeeding the major 3.0.0 release which introduced updated Node.js compatibility requirements. The project maintains an active development pace, with regular patch and minor updates focused on bug fixes and feature enhancements.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/mattallty/Caporal.js","tags":["javascript","cli","argument-parser","command","commander","clap","cli-app","minimist","optimist","typescript"],"install":[{"cmd":"npm install caporal","lang":"bash","label":"npm"},{"cmd":"yarn add caporal","lang":"bash","label":"yarn"},{"cmd":"pnpm add caporal","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For TypeScript and ES Modules, Caporal exports a namespace object. Do not use a default import.","wrong":"import prog from 'caporal';","symbol":"program","correct":"import * as prog from 'caporal';"},{"note":"This CommonJS `require` syntax is correct for Node.js environments that do not use ES Modules. However, Caporal v3.x is primarily ESM-first, ensure your project setup is compatible.","wrong":"import * as prog from 'caporal';","symbol":"program (CJS)","correct":"const prog = require('caporal');"},{"note":"Access type coercions (like `INT`, `FLOAT`, `BOOL`, `STRING`) as properties of the main `prog` import.","symbol":"INT (Type Coercion)","correct":"prog.INT"}],"quickstart":{"code":"#!/usr/bin/env node\nimport * as prog from 'caporal';\n\nprog\n  .version('1.0.0')\n  .description('A simple deployment CLI application')\n  .command('deploy', 'Deploy an application to a specified environment')\n  .argument('<appName>', 'The name of the application to deploy', /^myapp|their-app$/)\n  .argument('[environment]', 'The target environment (dev, staging, production)', /^dev|staging|production$/, 'local')\n  .option('--tail <lines>', 'Tail log lines after deployment', prog.INT, 10)\n  .option('--force', 'Force deployment even if warnings exist', prog.BOOL, false)\n  .action(async (args, options, logger) => {\n    const { appName, environment } = args;\n    const { tail, force } = options;\n\n    logger.info(`Deploying application: ${appName}`);\n    logger.info(`Target environment: ${environment}`);\n    logger.info(`Tail ${tail} log lines: ${tail > 0}`);\n    logger.info(`Force deploy: ${force}`);\n\n    if (force) {\n      logger.warn('Forcing deployment, ignoring warnings...');\n    }\n\n    // Simulate deployment process\n    await new Promise(resolve => setTimeout(resolve, 1500));\n\n    logger.info(`Application '${appName}' deployed to '${environment}' successfully.`);\n    if (tail > 0) {\n      logger.info(`Tailing last ${tail} log lines...`);\n      // Simulate log tailing\n      for (let i = 1; i <= tail; i++) {\n        logger.info(`[${new Date().toISOString()}] Log line ${i}`);\n      }\n    }\n  });\n\nprog.parse(process.argv);","lang":"typescript","description":"This quickstart demonstrates a simple 'deploy' command with required and optional arguments, along with boolean and integer options. It showcases Caporal's argument validation, type coercion, and integrated logger for informative output."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or higher, or explicitly lock your Caporal dependency to `<3.0.0`.","message":"Caporal v3.0.0 introduced a breaking change by dropping support for Node.js versions older than 16. Applications running on Node.js < 16 will fail to run or install when upgrading to Caporal v3.x.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure any variadic argument definition (`.argument('<items...>')`) is positioned as the final argument in your command definition chain.","message":"When defining variadic arguments (e.g., `...items`), they must always be the last argument specified for a command. Placing them anywhere else will lead to incorrect parsing behavior or errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If experiencing import errors, verify your `tsconfig.json` (`moduleResolution`, `module`) and `package.json` (`type`) settings. Consider clearing `node_modules` and reinstalling, or testing with specific patch versions if issues persist.","message":"Recent v3.1.x releases (specifically 3.1.5) indicate fixes related to module exports. Users might encounter issues with imports or module resolution depending on their build setup or specific Node.js version, especially when transitioning between Caporal versions or module systems.","severity":"gotcha","affected_versions":">=3.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npm install caporal` or `yarn add caporal` in your project directory.","cause":"The Caporal package is not installed or the Node.js module resolver cannot find it.","error":"Error: Cannot find module 'caporal'"},{"fix":"For ES Modules/TypeScript, use `import * as prog from 'caporal';`. For CommonJS, use `const prog = require('caporal');`. Ensure your project's `package.json` `\"type\": \"module\"` is set correctly for ESM.","cause":"This typically occurs when mixing module systems (e.g., using `require()` in an ES Module context or `import` in a CommonJS context) or when the imported symbol name doesn't match the export.","error":"ReferenceError: prog is not defined"},{"fix":"Upgrade your Node.js environment to version 16 or higher using a tool like `nvm` or by installing a newer version directly.","cause":"You are attempting to use Caporal v3.x or newer with a Node.js version below the minimum requirement of 16.","error":"This module requires Node.js >= 16. Current version: vX.Y.Z"}],"ecosystem":"npm"}