{"id":15987,"library":"commandpost","title":"Commandpost CLI Parser","description":"Commandpost is a command-line option parser library for Node.js, designed with a strong emphasis on TypeScript developer experience while remaining fully compatible with JavaScript projects. It provides a structured, chainable API for defining root commands, sub-commands, various types of options (e.g., flags, parameters), and arguments (required, optional, variadic). Inspired by the popular `commander` library, Commandpost differentiates itself by addressing `commander`'s limitations regarding robust TypeScript type inference and usage, offering a more type-safe approach to CLI development. The current stable version is 1.4.0, with releases historically following an irregular cadence based on community contributions and author availability, rather than fixed schedules. Key features include automatic help message generation, versioning, and descriptive capabilities for commands and options. Its core strength lies in enabling developers to build type-safe CLI applications with a familiar, fluid API.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/vvakame/commandpost","tags":["javascript"],"install":[{"cmd":"npm install commandpost","lang":"bash","label":"npm"},{"cmd":"yarn add commandpost","lang":"bash","label":"yarn"},{"cmd":"pnpm add commandpost","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library is designed for namespace imports (`import * as commandpost`) in both TypeScript and ESM environments, not direct named imports.","wrong":"import { create } from 'commandpost'; // Incorrect: 'create' is not a named export","symbol":"create","correct":"import * as commandpost from 'commandpost'; commandpost.create(...)"},{"note":"The `exec` function is part of the `commandpost` namespace and is called to parse `process.argv` and trigger the appropriate command action.","wrong":"import { exec } from 'commandpost'; // Incorrect: 'exec' is not a named export","symbol":"exec","correct":"import * as commandpost from 'commandpost'; commandpost.exec(root, process.argv)"},{"note":"While CommonJS `require` works, the library's primary design for TypeScript and ESM encourages the `import * as` syntax for better type inference.","wrong":"const commandpost = require('commandpost'); // CommonJS import","symbol":"commandpost","correct":"import * as commandpost from 'commandpost';"}],"quickstart":{"code":"import * as commandpost from 'commandpost';\n\nlet root = commandpost\n\t.create<{ spice: string[]; }, { food: string; }>( \"dinner <food>\")\n\t.version(\"1.0.0\", \"-v, --version\")\n\t.description(\"today's dinner!\")\n\t.option(\"-s, --spice <name>\", \"What spice do you want? default: pepper\")\n\t.action((opts, args) => {\n\t\tconsole.log(`Your dinner is ${args.food} with ${opts.spice[0] || \"pepper\"}!`);\n\t});\n\ncommandpost\n\t.exec(root, process.argv)\n\t.catch(err => {\n\t\tif (err instanceof Error) {\n\t\t\tconsole.error(err.stack);\n\t\t} else {\n\t\t\tconsole.error(err);\n\t\t}\n\t\tprocess.exit(1);\n\t});","lang":"typescript","description":"Sets up a basic CLI command `dinner <food>` with an optional `--spice` flag. This example demonstrates defining commands, parsing options and arguments, and handling execution errors."},"warnings":[{"fix":"When expecting a single string value for an option, access the first element in your action handler (e.g., `opts.spice[0]`). For options without parameters (flags), the value converts to `boolean`.","message":"Options defined with a parameter (e.g., `-s, --spice <name>`) are typed as a string array (`string[]`) by default, even if only a single value is expected. This is due to how variadic parameters are handled.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the `commandpost` documentation and examples, particularly the `example/usage.ts` file on GitHub, to understand its specific API patterns and TypeScript type definitions.","message":"Users migrating from `commander` may encounter subtle API differences or different type inference behaviors, as `commandpost` prioritizes TypeScript-friendliness over strict API parity with `commander`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always chain a `.catch()` block to `commandpost.exec()` to provide user-friendly error messages and ensure the process exits with an appropriate error code.","message":"Unhandled errors during command execution can lead to abrupt process termination. The `exec` method returns a Promise, which should be caught to handle parsing errors or exceptions thrown within your command actions gracefully.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Define the option using `.option('-f, --foo', 'Description')` on your command, or explicitly allow unknown options by calling `.allowUnknownOption()` on the command definition.","cause":"An unrecognized command-line option was passed that was not explicitly defined using `.option()` on the current command or its ancestors.","error":"error: unknown option '--foo'"},{"fix":"Ensure all required arguments are provided on the command line when executing. For example, if `<food>` is required, invoke as `cli.js <food_value>`.","cause":"A command was invoked without providing a required argument that was defined in its signature (e.g., `commandpost.create('cmd <arg>')`).","error":"error: missing required argument <argument_name>"},{"fix":"For TypeScript and ESM, use `import * as commandpost from 'commandpost';`. If strictly using CommonJS, ensure `const commandpost = require('commandpost');` is used, and functions are called as `commandpost.create()`.","cause":"The `commandpost` library was imported incorrectly, leading to the `create` function not being accessible on the imported object. This commonly occurs with incorrect named imports or using `require` when `import * as` is expected.","error":"TypeError: commandpost.create is not a function"}],"ecosystem":"npm"}