jackspeak CLI Argument Parser

4.2.3 · active · verified Tue Apr 21

jackspeak is a strict command-line argument parser for Node.js, currently at version 4.2.3. It focuses on rigorous validation of string, boolean, and number options, reading from both command-line arguments and environment variables. The library leverages a fluent, chainable API starting with `jack()`, which returns a `Jack` object for defining flags, options, and positionals. A key differentiator is its automatic type inference for TypeScript when defining configurations via object literals, ensuring strong typing for parsed values. It also supports automatic generation of `usage`/`help` banners and integrates environmental variable handling via an `envPrefix`, allowing configuration to be passed easily to child processes. Its minimal dependency footprint, especially the `/min` export introduced in v4.2, makes it suitable for CLI tools where startup performance is crucial. The project maintains an active development status with a positive version release cadence, typically releasing new versions within a three-month period.

Common errors

```
Error: Unrecognized option: --unknown-arg
```
cause An argument or flag was provided on the command line that was not defined in the `jackspeak` configuration.

fix Add the missing option, flag, or positional definition to your `jack().flag()`, `jack().opt()`, `jack().optList()`, or ensure `allowPositionals` is set to `true` (default).
```
Error: Invalid value for option <optionName>: <value>
```
cause The value provided for a configured option did not pass the validation rules (e.g., a string for a number option, or a value not in `validOptions`).

fix Review the option's definition in your `jack()` configuration and ensure the input from the command line or environment matches the expected type and validation criteria.
```
TypeError: jack is not a function
```
cause The `jack` function was imported incorrectly. This often happens when attempting a default import (`import jack from '...'`) for a named export, or using CommonJS `require` for an ESM-only package/export.

fix For ES Modules, use a named import: `import { jack } from 'jackspeak'` or `import { jack } from 'jackspeak/min'`. For CommonJS, use `const { jack } = require('jackspeak')`.

Warnings

breaking jackspeak v4.0.0 and later require modern Node.js versions. The `engines` field in `package.json` specifies Node.js 20 or newer (`20 || >=22`).
Fix: Ensure your project's Node.js environment is updated to version 20 or higher to meet the minimum engine requirements.
breaking Custom error fields were moved to the `cause` property of error objects in v3.0.0 to align with standard JavaScript error handling.
Fix: Update your error handling logic to access custom properties (if any) via the `cause` property of the thrown error.
gotcha jackspeak is designed for strict parsing. Any command-line arguments or environment variables not explicitly defined in the `jack()` configuration will cause an error to be thrown.
Fix: Always explicitly define all expected arguments, flags, and options in your `jackspeak` configuration. Wrap `.parse()` calls in a `try...catch` block for robust error handling in production CLI tools.
gotcha When `envPrefix` is configured, `jackspeak` writes parsed values back to `process.env`. This can unintentionally overwrite existing environment variables or affect child processes if not managed carefully.
Fix: To prevent unintended side effects, consider providing a custom `env` object to `jack()` instead of relying on `process.env`. Explicitly unset or manage environment variables if child process isolation is critical.
gotcha Some CommonJS projects using older package managers (e.g., Yarn v1) might encounter `ERR_REQUIRE_ESM` errors due to transitive dependencies like `cliui` being resolved as ES Modules.
Fix: Use npm as your package manager, which typically handles dependency resolution more robustly for hybrid modules. Alternatively, upgrade to a newer package manager, or for critical compatibility, consider pinning `jackspeak` to an older version or manually resolving problematic transitive dependencies in your `package.json`.

Install

npm install jackspeak npm
yarn add jackspeak yarn
pnpm add jackspeak pnpm

Imports

jack
wrong:
```
import jack from 'jackspeak'
```
correct:
```
import { jack } from 'jackspeak'
```
Primary entry point. CommonJS `require` is supported via package `exports` but ESM `import` is preferred since v2. For optimal CLI startup, consider `jackspeak/min`.
jack
wrong:
```
import jack from 'jackspeak/min'
```
correct:
```
import { jack } from 'jackspeak/min'
```
Recommended for CLI tools to minimize startup time, as this export has no external dependencies. Available since v4.2.
Jack
```
import type { Jack } from 'jackspeak'
```
TypeScript type for the parser instance, enabling type-safe chaining and configuration. The library was rewritten as a hybrid TypeScript module in v2.0.

Quickstart

Demonstrates basic argument parsing, flag handling, option lists, and environment variable integration using the `jackspeak/min` entry point.

import { jack } from 'jackspeak/min'

const { positionals, values } = jack({ envPrefix: 'FOO' })
  .flag({
    asdf: { description: 'sets the asfd flag', short: 'a', default: true },
    'no-asdf': { description: 'unsets the asdf flag', short: 'A' },
    foo: { description: 'another boolean', short: 'f' },
  })
  .optList({
    'ip-addrs': {
      description: 'addresses to ip things',
      delim: ',', // defaults to '\n'
      default: ['127.0.0.1'],
    },
  })
  .parse([
    'some',
    'positional',
    '--ip-addrs',
    '192.168.0.1',
    '--ip-addrs',
    '1.1.1.1',
    'args',
    '--foo', // sets the foo flag
    '-A', // short for --no-asdf, sets asdf flag to false
  ])

console.log(process.env.FOO_ASDF) // '0'
console.log(process.env.FOO_FOO) // '1'
console.log(values) // { /* ... parsed values ... */ }
console.log(process.env.FOO_IP_ADDRS) // '192.168.0.1,1.1.1.1'
console.log(positionals) // ['some', 'positional', 'args']

view raw JSON →