argp: Command-line Option Parser

1.0.4 · maintenance · verified Tue Apr 21

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.

Common errors

```
TypeError: argp.description is not a function
```
cause 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'
```
cause 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'
```
cause 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.

Warnings

breaking 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()`.
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(...)`.
gotcha 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.
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()`.
gotcha 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.
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.
gotcha 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.
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.

Install

npm install argp npm
yarn add argp yarn
pnpm add argp pnpm

Imports

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

Quickstart

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

view raw JSON →