Registry / http-networking / argp

argp

JSON →
library2.2.0jsnpmunverified

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.

http-networking
npm install argp
github ↗package ↗
INSTALL
IMPORT
SIG · ARGP
A
argp
http-networkingjavascriptv2.2.0
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.

argp module
✓ const argp = require('argp');
✗ import argp from 'argp';
This package is primarily CommonJS. Direct ESM imports are not supported without a transpilation step or wrapper.
createParser
✓ const parser = require('argp').createParser({ once: true });
✗ import { createParser } from 'argp';
Since v1, parser instances must be created via createParser(). The `once: true` option uncaches the module after parsing.
readPackage
✓ const argv = require('argp').readPackage().argv();
✗ import { readPackage } from 'argp';
Used to populate description, email, and version from a package.json file. It performs a synchronous filesystem operation.

Demonstrates basic parsing of GNU-style options and arguments, automatic help message generation, and version display.

const argp = require('argp'); // If not using multiple parser instances or reusing a parser, 'once: true' // guarantees a zero memory footprint by uncaching the module. const argv = argp.createParser({ once: true }) .description('Sample app.') .email('a@b.c') .body() // Defines arguments and options while simultaneously configuring help text. .text(' Arguments:') .argument('arg', { description: 'Sample argument' }) .text('\n Options:') .option({ short: 'o', long: 'opt', description: 'Sample option' }) .help() .version('v1.2.3') .argv(); console.log(argv); // To test, run: // node your-script.js --opt value --arg argument_value // node your-script.js --help // node your-script.js --version
argp --version
Debug
Known issues
breakingVersion 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()`.
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(...)`.
affects: >=1.0.0
gotchaThe `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.
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()`.
affects: >=0.10
gotchaThe 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.
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.
affects: >=0.10
gotchaThe 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.
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.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: argp.description is not a function
Attempting to call parser configuration methods directly on the `argp` module object after upgrading to v1, which requires creating a parser instance first.
fix
Ensure you call `.createParser()` before chaining configuration methods: `require('argp').createParser().description(...)`.
SyntaxError: Named export 'createParser' not found. The requested module 'argp' does not provide an export named 'createParser'
Attempting to use ES module `import { createParser } from 'argp';` syntax with this CommonJS-only package.
fix
Use the CommonJS `require()` syntax: `const argp = require('argp'); const parser = argp.createParser();`.
Error: Unknown option '--unknown'
The parser encountered a command-line option that was not explicitly defined in the parser configuration.
fix
Define the option using `.option()` in your parser configuration or ensure that arguments are being passed correctly and not interpreted as undefined options.
Upgrade
Version history
2.2.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
22 hits · last 30 days
node
16
Amazon
1
OpenAI (training)
1
Resources
githubhttps://github.com/gagle/node-argp ↗
packagehttps://www.npmjs.com/package/argp ↗
argp — npm install argp · libregistry