{"id":12822,"library":"arg-parser","title":"Node CLI Argument Parser","description":"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.","status":"maintenance","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/tborychowski/node-arg-parser","tags":["javascript","args","parser"],"install":[{"cmd":"npm install arg-parser","lang":"bash","label":"npm"},{"cmd":"yarn add arg-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add arg-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Args = require('arg-parser');","symbol":"Args","correct":"import Args from 'arg-parser';"},{"note":"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.","symbol":"Args (Type)","correct":"import type Args from 'arg-parser';"}],"quickstart":{"code":"import Args from 'arg-parser';\n\nconst args = new Args(\n    'MyCLIApp',\n    '1.0.0',\n    'A simple command-line application',\n    'For more details, visit our documentation.'\n);\n\nargs.add({ name: 'input', desc: 'input file path', switches: [ '-i', '--input-file'], value: 'file', required: true });\nargs.add({ name: 'output', desc: 'output directory', switches: [ '-o', '--output-dir'], value: 'dir', default: './output' });\nargs.add({ name: 'force', desc: 'force overwrite existing files', switches: [ '-f', '--force-overwrite'] });\nargs.add({ name: 'verbose', desc: 'enable verbose logging', switches: [ '-v', '--verbose'] });\nargs.add({ name: 'message', desc: 'a custom message', required: false, value: 'text' });\n\n// Simulate process.argv for testing or provide actual arguments\n// For a real run, this would implicitly use process.argv\nconst customArgs = ['--input-file', 'data.txt', '--output-dir', 'results', '--force-overwrite', 'Hello World'];\n\nif (args.parse(customArgs)) {\n  console.log('Parsed arguments:', args.params);\n} else {\n  // args.parse() will automatically display help and exit on error\n  console.error('Failed to parse arguments. See help above.');\n}\n\n/* Example of expected output if `data.txt` and `Hello World` are provided:\nParsed arguments: {\n  input: 'data.txt',\n  output: 'results',\n  force: true,\n  verbose: false,\n  message: 'Hello World'\n}\n*/","lang":"javascript","description":"Demonstrates defining various types of command-line arguments (required, optional, switches, values) and parsing them using the `Args` class."},"warnings":[{"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.","message":"Despite `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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"The `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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"If `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import `arg-parser` using CommonJS `require()` syntax instead of ES Module `import`.","error":"TypeError: Args is not a constructor"},{"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`.","cause":"A required argument, specified with `required: true` in the `add` method, was not provided in the command line.","error":"Error: the following arguments are required: <argument_name>"},{"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.","cause":"The command line included a switch (e.g., `--unknown-switch`) that was not defined using `args.add()` in the parser configuration.","error":"Unknown argument: --unknown-switch"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null}