Commander Extra Typings

@commander-js/extra-typings is a TypeScript-only companion to the popular Commander CLI framework. It supplies enhanced typings that infer strong, precise types for the parameters of your action handlers, including options, and for the object returned by .opts().

The runtime is still provided by Commander itself; this package changes nothing at runtime and instead layers richer generics on top so the compiler can catch mistakes in your command definitions. You import from @commander-js/extra-typings instead of commander and immediately get type-safe options and arguments across your CLI.

What You Get

• Inferred types for every parameter of your action handler callbacks
• Strongly-typed objects returned by .opts()
• A drop-in import that swaps commander’s types without changing runtime behavior
• Compatibility versioning aligned to the matching commander major/minor release
• Full TypeScript 5.0+ support with no runtime dependencies of its own

Common Use Cases

• Adding compile-time safety to Commander-based CLI tools
• Catching mismatched option and argument usage before runtime
• Improving editor autocompletion for command options and handlers
• Migrating existing Commander projects to fully typed command definitions

Under The Hood

Architecture - The package is almost entirely a declaration file (index.d.ts) that re-exports Commander’s runtime while overlaying generic wrapper types on Command, Option, and Argument. Each builder method (option, argument, requiredOption) is typed to accumulate its result into the Command’s generic parameters, so by the time you reach .action() or .opts() the compiler has assembled a precise type describing every declared value. index.js simply re-exports commander at runtime.

Tech Stack - TypeScript 5.0+ typings with a near-empty JavaScript runtime shim. It declares commander as a peer dependency, uses ESLint for linting, and ships tsconfig and example projects to validate the generics.

Code Quality - The repository includes a tests directory with type-level and behavioral checks, a CHANGELOG, security policy, and CONTRIBUTING guide. As part of the official Commander.js org, it follows the parent project’s conventions and version-alignment discipline.

API Design - Adoption is a single import swap, keeping the familiar Commander fluent API while adding inference. The main cost is more complex generic error messages, which the README documents under limitations; examples help developers understand the trade-offs.