command-line-args

command-line-args parses process.argv into a plain JavaScript object based on an array of option definitions you supply. Each definition names the option, its type (a setter function such as Boolean, Number, or String), any single-character alias, and whether it accepts multiple values or acts as the default (positional) option.

Beyond basic flag parsing, it supports git-style command syntax and Docker-style command/sub-command syntax, camel-casing of hyphenated option names, case-insensitive matching, and both strict and partial parsing modes (the latter collecting unrecognized arguments into an _unknown array instead of throwing). It pairs with the companion command-line-usage package to auto-generate --help output from the same definitions.

What You Get

• A single commandLineArgs(optionDefinitions, options) function that returns a parsed options object
• Support for boolean flags, aliases, multiple values, and a defaultOption for unlabeled positional arguments
• Type coercion via setter functions (Boolean, Number, String, or any custom function) applied to each raw value
• Git-style and Docker-style command/sub-command parsing patterns for building multi-command CLIs
• Strict mode (throws typed errors like UNKNOWN_OPTION, UNKNOWN_VALUE, ALREADY_SET) or partial/stopAtFirstUnknown modes for lenient parsing
• camelCase and caseInsensitive parsing options for flexible option-name handling

Common Use Cases

• Parsing flags and options for a custom Node.js CLI tool without hand-rolling argv iteration
• Building git-style CLIs with a command name followed by command-specific options
• Building Docker-style CLIs with chained commands and sub-commands, each with their own options
• Generating a —help usage guide by feeding the same option definitions to command-line-usage

Under The Hood

Architecture index.js exposes a single commandLineArgs() function that builds an ArgvParser (lib/argv-parser.js) driven by a Definitions collection (lib/option-definitions.js) constructed from the caller’s option-definition objects (lib/option-definition.js). ArgvParser implements a generator-based Symbol.iterator that walks process.argv (or a supplied array via lib/argv-tools.js’s ArgvArray), yielding one argInfo event per token — set, unknown_option, unknown_value — while tracking cross-iteration state such as singularDefaultSet and unknownFound. index.js consumes this iterator, accumulating parsed values into an Output or OutputGrouped (lib/output.js, lib/output-grouped.js) built from Option instances (lib/option.js), then serializes the result via toObject(). This event-driven, single-pass generator design cleanly separates tokenizing/matching from value accumulation, so a new argument notation is a localized change to argv-tools.js and the parser’s iterator rather than a module-wide one.

Tech Stack Pure ESM (type: module) with a generated CommonJS build (dist/index.cjs, produced by the maintainer’s own @75lb/nature tool) exposed through package.json’s exports map for dual-format consumption. Runtime dependencies are minimal and maintainer-authored: array-back, find-replace, lodash.camelcase, and typical for lightweight type checks; @75lb/nature is listed only as an optional peer dependency used for the dist/doc build tooling, not at runtime. Tests run via test-runner (also 75lb’s own micro test runner) through npm scripts, and CI is GitHub Actions exercising the suite across Node 12 through 25 on both Ubuntu and Windows.

Code Quality lib/ holds roughly 950 lines across eight small, single-responsibility files, each documented with JSDoc @param/@throws blocks that double as the source for the generated doc/API.md. test/ has 30-plus files, one per behavior (alias.js, camel-case.js, default-option.js, exceptions-already-set.js, grouping.js, and more), giving explicit coverage of each documented error path and notation style rather than one monolithic test file. Error handling is explicit and typed — thrown errors carry a name (UNKNOWN_OPTION, UNKNOWN_VALUE, ALREADY_SET, INVALID_DEFINITIONS) plus a relevant property (optionName or value) instead of swallowing failures. No TypeScript or static type checker is used; JSDoc comments are the only type documentation, and StandardJS (via a standard field in package.json) stands in for a dedicated ESLint config.

API Design The public surface is a single function call — an array of plain {name, alias, type} definitions plus an options bag — with no classes to instantiate and no builder chain, matching the low-ceremony bar set by comparable argument parsers. The same definitions array can be fed into the separate command-line-usage package to auto-generate —help text with no duplication. The tradeoff is that git-style and Docker-style command/sub-command parsing isn’t a first-class API: it’s documented as a manual composition pattern requiring two passes over definitions (once for the command, once for that command’s own options), so multi-command CLIs require the caller to wire the pattern up rather than getting dedicated subcommand support.