Registry / arg-parser

arg-parser

library1.0.5jsnpmunverified

arg-parser (v2.0.1) is a lightweight, declarative command-line interface (CLI) argument parser specifically designed for Node.js applications. It enables developers to define and parse application-specific command-line arguments, including switches, required positional arguments, and descriptive help messages. The library allows for clear separation of argument definition from parsing logic, providing a structured approach to CLI development. While functional, the package has not seen active development or releases in several years, despite specifying Node.js >=18.0.0 in its `engines` field. This contrasts with more actively maintained alternatives like `yargs` or `commander.js`, which offer more advanced features, active community support, and frequent updates for modern Node.js environments. Its key differentiator is simplicity and a minimal API for basic argument parsing requirements.

npm install arg-parser

github ↗package ↗

INSTALL

IMPORT

SIG · ARG-PARSER

arg-parser

javascriptv1.0.5

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.

Args

✓ import Args from 'arg-parser';

✗ const Args = require('arg-parser');

The library primarily uses ES Module syntax (`import`) as shown in its examples, fitting its Node.js >=18.0.0 requirement. Direct `require` might lead to issues with the default export.

Args (Type)

✓ import type Args from 'arg-parser';

Although the package itself does not ship with TypeScript definitions, users typically create a declaration file (`.d.ts`) or use JSDoc for type inference to benefit from tooling support.

Demonstrates defining various types of command-line arguments (required, optional, switches, values) and parsing them using the `Args` class.

import Args from 'arg-parser'; const args = new Args( 'MyCLIApp', '1.0.0', 'A simple command-line application', 'For more details, visit our documentation.' ); args.add({ name: 'input', desc: 'input file path', switches: [ '-i', '--input-file'], value: 'file', required: true }); args.add({ name: 'output', desc: 'output directory', switches: [ '-o', '--output-dir'], value: 'dir', default: './output' }); args.add({ name: 'force', desc: 'force overwrite existing files', switches: [ '-f', '--force-overwrite'] }); args.add({ name: 'verbose', desc: 'enable verbose logging', switches: [ '-v', '--verbose'] }); args.add({ name: 'message', desc: 'a custom message', required: false, value: 'text' }); // Simulate process.argv for testing or provide actual arguments // For a real run, this would implicitly use process.argv const customArgs = ['--input-file', 'data.txt', '--output-dir', 'results', '--force-overwrite', 'Hello World']; if (args.parse(customArgs)) { console.log('Parsed arguments:', args.params); } else { // args.parse() will automatically display help and exit on error console.error('Failed to parse arguments. See help above.'); } /* Example of expected output if `data.txt` and `Hello World` are provided: Parsed arguments: { input: 'data.txt', output: 'results', force: true, verbose: false, message: 'Hello World' } */

Debug

Known issues

gotchaDespite `package.json` specifying `"node": ">=18.0.0"`, the package has not received updates in several years. This might lead to compatibility issues with newer Node.js versions, dependency vulnerabilities, or unexpected behavior with modern ecosystem tools.

fix

Thoroughly test `arg-parser` with your specific Node.js version and project dependencies. Consider migrating to a more actively maintained CLI parser for long-term projects.

affects: >=2.0.0

breakingThe `add` method's `value` property is crucial for arguments that expect a string value (e.g., file paths). If `value` is omitted for such an argument, it will be treated as a boolean switch (flag) instead of expecting a subsequent value.

fix

Always explicitly set `value: 'file'` or `value: 'text'` (or similar descriptive string) in the `add` configuration object for arguments that are intended to receive a string value.

affects: >=1.0.0

gotchaThe `Args` constructor's parameters are positional and somewhat generic (`title`, `version`, `description`, `epilog`). Misordering them will result in incorrect CLI help output, which can be confusing for end-users.

fix

Always refer to the constructor signature: `new Args(cliName: string, cliVersion: string, cliDescription: string, cliEpilog: string);` to ensure the correct information is displayed in the generated `--help` message.

affects: >=1.0.0

gotchaIf `args.parse()` returns `false`, it indicates that an error occurred during parsing (e.g., missing required arguments, unknown switches). The library automatically prints help/error messages to `stderr` and calls `process.exit(1)`. This behavior cannot be easily overridden for custom error handling.

fix

Implement custom pre-parsing validation if you need more granular control over error messages or wish to prevent `process.exit()` in certain scenarios. Otherwise, rely on the library's built-in error reporting.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Args is not a constructor

Attempting to import `arg-parser` using CommonJS `require()` syntax instead of ES Module `import`.

fix

Change `const Args = require('arg-parser');` to `import Args from 'arg-parser';` Ensure your `package.json` has `"type": "module"` or your file uses the `.mjs` extension for ESM support in Node.js.

Error: the following arguments are required: <argument_name>

A required argument, specified with `required: true` in the `add` method, was not provided in the command line.

fix

Ensure all arguments marked as `required: true` are present in the command-line invocation, e.g., `node your-script.js --required-arg-name value`.

Unknown argument: --unknown-switch

The command line included a switch (e.g., `--unknown-switch`) that was not defined using `args.add()` in the parser configuration.

fix

Define all expected command-line switches using `args.add({ name: '...', switches: ['--unknown-switch'] })` or correct the typo in the command line if it was intended to be a known switch.

Upgrade

Version history

1.0.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/tborychowski/node-arg-parser ↗

packagehttps://www.npmjs.com/package/arg-parser ↗