{"id":15965,"library":"argp","title":"argp: Command-line Option Parser","description":"argp is a command-line option parser inspired by the GNU argp C library. It focuses on robust parsing of GNU-style options, automatic generation of comprehensive help, usage, and version messages with proper line-wrapping at 80 columns. A key design principle is its 'zero memory footprint' after parsing, achieved by uncaching the module and deleting properties once all input parameters are processed. The package, currently at stable version 1.0.4, offers basic error checking, support for command configuration, and an evented system for customization. It differentiates itself through its strict adherence to GNU-style parsing conventions and its minimal post-execution resource usage, making it suitable for CLI tools prioritizing resource efficiency and standard compliance.","status":"maintenance","version":"1.0.4","language":"javascript","source_language":"en","source_url":"git://github.com/gagle/node-argp","tags":["javascript","cli","options","parser","commands","arguments","getopt","argparse"],"install":[{"cmd":"npm install argp","lang":"bash","label":"npm"},{"cmd":"yarn add argp","lang":"bash","label":"yarn"},{"cmd":"pnpm add argp","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is primarily CommonJS. Direct ESM imports are not supported without a transpilation step or wrapper.","wrong":"import argp from 'argp';","symbol":"argp module","correct":"const argp = require('argp');"},{"note":"Since v1, parser instances must be created via createParser(). The `once: true` option uncaches the module after parsing.","wrong":"import { createParser } from 'argp';","symbol":"createParser","correct":"const parser = require('argp').createParser({ once: true });"},{"note":"Used to populate description, email, and version from a package.json file. It performs a synchronous filesystem operation.","wrong":"import { readPackage } from 'argp';","symbol":"readPackage","correct":"const argv = require('argp').readPackage().argv();"}],"quickstart":{"code":"const argp = require('argp');\n\n// If not using multiple parser instances or reusing a parser, 'once: true'\n// guarantees a zero memory footprint by uncaching the module.\nconst argv = argp.createParser({ once: true })\n    .description('Sample app.')\n    .email('a@b.c')\n    .body()\n        // Defines arguments and options while simultaneously configuring help text.\n        .text(' Arguments:')\n        .argument('arg', { description: 'Sample argument' })\n        .text('\\n Options:')\n        .option({ short: 'o', long: 'opt', description: 'Sample option' })\n        .help()\n        .version('v1.2.3')\n    .argv();\n\nconsole.log(argv);\n\n// To test, run:\n// node your-script.js --opt value --arg argument_value\n// node your-script.js --help\n// node your-script.js --version","lang":"javascript","description":"Demonstrates basic parsing of GNU-style options and arguments, automatic help message generation, and version display."},"warnings":[{"fix":"Prefix your parser configuration chain with `.createParser({ once: true })` or `.createParser()` if you need to reuse the parser. For example: `require(\"argp\").createParser({ once: true }).description(...)`.","message":"Version 1 introduced parser instances. Direct calls to methods like `.description()` on the `require('argp')` module object no longer work. You must first create a parser instance using `.createParser()`.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Be aware of its synchronous nature. If performance is extremely critical at startup or in a highly concurrent environment, consider manually providing metadata instead of relying on `readPackage()`.","message":"The `readPackage()` function, used to extract metadata from `package.json`, performs a synchronous filesystem operation (`fs.readFileSync`). While typically run early in a CLI tool's lifecycle, it can block the event loop for a brief period.","severity":"gotcha","affected_versions":">=0.10"},{"fix":"Use `require()` syntax for importing `argp`. If integrating into an ESM project, you might need to use a CommonJS wrapper or a transpilation step (e.g., Babel, TypeScript) to allow `require()` calls within ESM.","message":"The package is built for older Node.js environments (engines: `>=0.10`) and primarily uses CommonJS modules. It may not natively support ES Modules (ESM) syntax, potentially leading to issues in modern JavaScript projects that are ESM-first.","severity":"gotcha","affected_versions":">=0.10"},{"fix":"If you need to parse arguments multiple times or manage multiple distinct CLI contexts, omit the `once: true` option when calling `createParser()` or manually re-`require('argp')` for each new parsing cycle.","message":"The package's 'zero memory footprint' feature, enabled by `once: true`, unloads the module from the cache after `argv()` is called. While beneficial for memory, it means you cannot reuse the same module instance for subsequent parsing operations without re-requiring it.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you call `.createParser()` before chaining configuration methods: `require('argp').createParser().description(...)`.","cause":"Attempting to call parser configuration methods directly on the `argp` module object after upgrading to v1, which requires creating a parser instance first.","error":"TypeError: argp.description is not a function"},{"fix":"Use the CommonJS `require()` syntax: `const argp = require('argp'); const parser = argp.createParser();`.","cause":"Attempting to use ES module `import { createParser } from 'argp';` syntax with this CommonJS-only package.","error":"SyntaxError: Named export 'createParser' not found. The requested module 'argp' does not provide an export named 'createParser'"},{"fix":"Define the option using `.option()` in your parser configuration or ensure that arguments are being passed correctly and not interpreted as undefined options.","cause":"The parser encountered a command-line option that was not explicitly defined in the parser configuration.","error":"Error: Unknown option '--unknown'"}],"ecosystem":"npm"}