Registry / http-networking / args-parser

args-parser

JSON →
library1.3.0jsnpmunverified

args-parser is a minimalist command-line argument parser designed specifically for Node.js environments. Its current stable version is 1.3.0, and it maintains a relatively slow release cadence, reflecting its stable and focused scope. The library directly processes an array of strings, typically `process.argv`, transforming them into a straightforward JavaScript object. Flags are represented as boolean `true` values, while key-value pairs (e.g., `--key=value`) are parsed into string or numeric values accordingly. Its key differentiators include an extremely small footprint and a simple, direct API, making it an ideal choice for basic script argument handling where the overhead or extensive features of more complex parsers like `yargs` or `commander.js` are not required. It explicitly avoids advanced features such as extensive type coercion, positional arguments, aliases, or integrated help generation, focusing solely on efficient, no-frills flag and option parsing.

http-networking
npm install args-parser
github ↗package ↗
INSTALL
IMPORT
SIG · ARGS-PARSER
A
args-parser
http-networkingjavascriptv1.3.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.

argsParser
✓ const argsParser = require('args-parser'); const args = argsParser(process.argv);
✗ import argsParser from 'args-parser';
The package is CommonJS-only and exports the parsing function directly as its default. It expects `process.argv` or a similar string array as its argument.
parseArgs
✓ const parseArgs = require('args-parser'); const myArgs = parseArgs(['--config=dev', '-v']);
✗ const { parseArgs } = require('args-parser');
The module's default export is the parsing function itself. There are no named exports available.
Type Definition
✓ // No specific type definitions are shipped with the package, infer 'any' or define locally.
As of v1.3.0, `args-parser` does not ship with TypeScript type definitions. Users will need to declare types manually or rely on 'any'.

Demonstrates how to install and use `args-parser` to parse simulated command-line arguments, showing the resulting object structure and basic access patterns for flags and key-value options.

const argsParser = require('args-parser'); // Simulate command-line arguments const simulatedArgs = [ 'node', 'script.js', '--careful', '-dangerous', '--tomatoes=3', '--tonight', '--key=ek==', '--rate=4.5' ]; // In a real script, you'd use: const args = argsParser(process.argv); const args = argsParser(simulatedArgs); console.log('Parsed Arguments:'); console.log(args); if (args.careful) { console.log('Careful flag is set!'); } if (args.tomatoes) { console.log(`Number of tomatoes: ${args.tomatoes}`); // Note: args.tomatoes is a string '3' } if (args.rate) { console.log(`Rate value: ${parseFloat(args.rate)}`); // Type coercion often needed } // Example of accessing an argument that might not exist if (args.verbose === undefined) { console.log('Verbose flag was not provided.'); }
Debug
Known issues
gotchaThe package is CommonJS-only and does not natively support ES Modules (`import`/`export`) syntax. Attempting to import it directly in an ESM context will result in a runtime error.
fix
For ESM projects, use `const argsParser = require('args-parser');` within a wrapper that uses `createRequire` from the `module` package, or use a tool like Webpack/Rollup for bundling and CJS-to-ESM conversion.
affects: >=1.0.0
gotcha`args-parser` provides a very basic parsing mechanism. It does not include features commonly found in more robust CLI libraries, such as type validation (all values from `--key=value` are strings), default values, aliases, positional arguments, subcommands, or automatic help message generation.
fix
For applications requiring advanced CLI features, consider alternative libraries like `yargs`, `commander.js`, or `minimist` combined with custom logic for validation and defaults. If sticking with `args-parser`, implement all validation and defaults manually after parsing.
affects: >=1.0.0
gotchaArguments without an equals sign (`--flag`) are always parsed as `true` if present, and `undefined` if absent. There is no direct way to specify `false` for a flag from the command line, and `args-parser` does not provide an option to set default values for missing flags.
fix
Always check for `if (args.flag)` instead of `if (args.flag === true)`. Implement default values manually using the logical OR operator or nullish coalescing: `const myFlag = args.flag ?? false;`.
affects: >=1.0.0
gotchaValues parsed from `--key=value` are always treated as strings. While numbers might appear to parse correctly, they remain string types and require explicit type coercion (e.g., `parseInt`, `parseFloat`) if arithmetic operations or strict type checks are needed.
fix
Always explicitly convert string values to the desired type after parsing, for example: `const count = parseInt(args.count, 10);` or `const ratio = parseFloat(args.ratio);`.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: argsParser is not a function
The `require('args-parser')` call returns the parsing function directly, but the user is attempting to call a method on it (e.g., `argsParser.parse()`).
fix
Call the required module directly with the arguments array: `const args = require('args-parser')(process.argv);`
ReferenceError: require is not defined in ES module scope
Attempting to use `require()` in a JavaScript file that is being interpreted as an ES Module (e.g., due to `"type": "module"` in `package.json` or a `.mjs` extension).
fix
If running Node.js v12.20.0+, you can use `const { createRequire } = require('module'); const requireCjs = createRequire(import.meta.url); const argsParser = requireCjs('args-parser');`. Otherwise, convert your file to CommonJS or use a bundler.
TypeError: Cannot read properties of undefined (reading 'myFlag')
The user is attempting to access a property (flag or option) that was not provided in the command-line arguments, and expects it to be `false` or some default, but `args-parser` returns `undefined` for missing arguments.
fix
Always check for the existence of the property or provide a fallback value: `const myFlag = args.myFlag ?? false;` or `if (args.myFlag) { /* ... */ }`.
Upgrade
Version history
1.3.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
21 hits · last 30 days
node
18
OpenAI (training)
1
Resources
githubhttps://github.com/eveningkid/args-parser ↗
packagehttps://www.npmjs.com/package/args-parser ↗
args-parser — npm install args-parser · libregistry