commandpost

library1.4.0jsnpmunverified

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.

web-framework

npm install commandpost

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · COMMANDPOST

commandpost

web-frameworkjavascriptv1.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

create

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

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

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

exec

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

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

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

commandpost

✓ import * as commandpost from 'commandpost';

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

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

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); });

Debug

Known issues

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

affects: >=1.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

error: unknown option '--foo'

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>

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

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

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vvakame/commandpost ↗

packagehttps://www.npmjs.com/package/commandpost ↗

homepagehttps://commandpost.js.org ↗