Commandpost CLI Parser

Common errors

• error: unknown option '--foo'

  cause An unrecognized command-line option was passed that was not explicitly defined using `.option()` on the current command or its ancestors.
  fix Define the option using `.option('-f, --foo', 'Description')` on your command, or explicitly allow unknown options by calling `.allowUnknownOption()` on the command definition.

• error: missing required argument <argument_name>

  cause A command was invoked without providing a required argument that was defined in its signature (e.g., `commandpost.create('cmd <arg>')`).
  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>`.

• TypeError: commandpost.create is not a function

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

Warnings

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

Install

• npm install commandpost npm
• yarn add commandpost yarn
• pnpm add commandpost pnpm

Imports

• create
  wrong:

  import { create } from 'commandpost'; // Incorrect: 'create' is not a named export

  correct:

  import * as commandpost from 'commandpost'; commandpost.create(...)

  The library is designed for namespace imports (`import * as commandpost`) in both TypeScript and ESM environments, not direct named imports.
• exec
  wrong:

  import { exec } from 'commandpost'; // Incorrect: 'exec' is not a named export

  correct:

  import * as commandpost from 'commandpost'; commandpost.exec(root, process.argv)

  The `exec` function is part of the `commandpost` namespace and is called to parse `process.argv` and trigger the appropriate command action.
• commandpost
  wrong:

  const commandpost = require('commandpost'); // CommonJS import

  correct:

  import * as commandpost from 'commandpost';

  While CommonJS `require` works, the library's primary design for TypeScript and ESM encourages the `import * as` syntax for better type inference.

Quickstart

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.

import * as commandpost from 'commandpost';

let root = commandpost
	.create<{ spice: string[]; }, { food: string; }>( "dinner <food>")
	.version("1.0.0", "-v, --version")
	.description("today's dinner!")
	.option("-s, --spice <name>", "What spice do you want? default: pepper")
	.action((opts, args) => {
		console.log(`Your dinner is ${args.food} with ${opts.spice[0] || "pepper"}!`);
	});

commandpost
	.exec(root, process.argv)
	.catch(err => {
		if (err instanceof Error) {
			console.error(err.stack);
		} else {
			console.error(err);
		}
		process.exit(1);
	});