{"id":15654,"library":"jackspeak","title":"jackspeak CLI Argument Parser","description":"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.","status":"active","version":"4.2.3","language":"javascript","source_language":"en","source_url":"https://github.com/isaacs/jackspeak","tags":["javascript","argument","parser","args","option","flag","cli","command","line","typescript"],"install":[{"cmd":"npm install jackspeak","lang":"bash","label":"npm"},{"cmd":"yarn add jackspeak","lang":"bash","label":"yarn"},{"cmd":"pnpm add jackspeak","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary entry point. CommonJS `require` is supported via package `exports` but ESM `import` is preferred since v2. For optimal CLI startup, consider `jackspeak/min`.","wrong":"import jack from 'jackspeak'","symbol":"jack","correct":"import { jack } from 'jackspeak'"},{"note":"Recommended for CLI tools to minimize startup time, as this export has no external dependencies. Available since v4.2.","wrong":"import jack from 'jackspeak/min'","symbol":"jack","correct":"import { jack } from 'jackspeak/min'"},{"note":"TypeScript type for the parser instance, enabling type-safe chaining and configuration. The library was rewritten as a hybrid TypeScript module in v2.0.","symbol":"Jack","correct":"import type { Jack } from 'jackspeak'"}],"quickstart":{"code":"import { jack } from 'jackspeak/min'\n\nconst { positionals, values } = jack({ envPrefix: 'FOO' })\n  .flag({\n    asdf: { description: 'sets the asfd flag', short: 'a', default: true },\n    'no-asdf': { description: 'unsets the asdf flag', short: 'A' },\n    foo: { description: 'another boolean', short: 'f' },\n  })\n  .optList({\n    'ip-addrs': {\n      description: 'addresses to ip things',\n      delim: ',', // defaults to '\\n'\n      default: ['127.0.0.1'],\n    },\n  })\n  .parse([\n    'some',\n    'positional',\n    '--ip-addrs',\n    '192.168.0.1',\n    '--ip-addrs',\n    '1.1.1.1',\n    'args',\n    '--foo', // sets the foo flag\n    '-A', // short for --no-asdf, sets asdf flag to false\n  ])\n\nconsole.log(process.env.FOO_ASDF) // '0'\nconsole.log(process.env.FOO_FOO) // '1'\nconsole.log(values) // { /* ... parsed values ... */ }\nconsole.log(process.env.FOO_IP_ADDRS) // '192.168.0.1,1.1.1.1'\nconsole.log(positionals) // ['some', 'positional', 'args']","lang":"typescript","description":"Demonstrates basic argument parsing, flag handling, option lists, and environment variable integration using the `jackspeak/min` entry point."},"warnings":[{"fix":"Ensure your project's Node.js environment is updated to version 20 or higher to meet the minimum engine requirements.","message":"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`).","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update your error handling logic to access custom properties (if any) via the `cause` property of the thrown error.","message":"Custom error fields were moved to the `cause` property of error objects in v3.0.0 to align with standard JavaScript error handling.","severity":"breaking","affected_versions":"3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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).","cause":"An argument or flag was provided on the command line that was not defined in the `jackspeak` configuration.","error":"Error: Unrecognized option: --unknown-arg"},{"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.","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`).","error":"Error: Invalid value for option <optionName>: <value>"},{"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')`.","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.","error":"TypeError: jack is not a function"}],"ecosystem":"npm"}