Registry / http-networking / process.argv

process.argv

library1.0.0jsnpmunverified

process.argv is a lightweight and minimal CLI argument parser for Node.js. The current stable version is 1.0.0. While the package does not have a rapid release cadence, its GitHub repository shows copyright updates extending to 2024 and active CI workflows, indicating ongoing maintenance rather than abandonment. It differentiates itself from more feature-rich alternatives like `yargs` or `commander` by intentionally omitting common conveniences such as shortcut flags (e.g., `-f`), built-in help message generation, and space-separated argument values (e.g., `--foo bar`). Instead, it processes arguments strictly in the `--key=value` format, automatically handling nested object structures from hyphenated keys (e.g., `--bar-buz` maps to `config.bar.buz`). This design philosophy prioritizes a small footprint and explicit parsing logic, requiring developers to implement higher-level CLI features themselves.

http-networking

npm install process.argv

github ↗package ↗

INSTALL

IMPORT

SIG · PROCESS.ARGV

process.argv

http-networkingjavascriptv1.0.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.

argv

✓ import argv from 'process.argv'

✗ import { argv } from 'process.argv'

The package exports a default function, not named exports, for ESM/TypeScript environments.

argv

✓ const argv = require('process.argv')

✗ const { argv } = require('process.argv')

CommonJS environments should use the default import pattern.

processArgv

✓ const processArgv = argv(process.argv.slice(2));

The `argv` function expects an array of arguments, typically `process.argv.slice(2)` to exclude Node.js executable path and script path.

Demonstrates parsing CLI arguments into a typed configuration object, applying defaults, and accessing positional arguments. The example includes a `mockArgs` array for easy testing without actual CLI execution.

import argv from 'process.argv'; interface Config { foo: string; bar: { buz: string; }; qux?: boolean; '--'?: string[]; // To capture positional arguments } // Simulate process.argv for demonstration const mockArgs = ['node', 'cli.js', '--foo=hello', '--bar-buz=world', 'file1.txt', 'file2.txt']; // In a real CLI, use: argv(process.argv.slice(2)) const processArgv = argv(mockArgs.slice(2)); const config = processArgv<Config>({ foo: 'defaultFoo', bar: { buz: 'defaultBuz' }, qux: false }); console.log('Parsed Configuration:', config); console.log('Foo:', config.foo); // Should be 'hello' console.log('Bar Buz:', config.bar.buz); // Should be 'world' console.log('Qux (default):', config.qux); // Should be false // Access positional arguments (e.g., file1.txt, file2.txt) const positionalArgs = config['--'] || []; console.log('Positional Arguments:', positionalArgs);

Debug

Known issues

gotchaThe parser does not support shortcut flag names (e.g., -f for --force); full option names like `--force` must always be used.

fix

Always use the full, long-form argument names (e.g., `--verbose` instead of `-v`).

affects: >=1.0.0

gotchaThe library does not provide built-in help message generation or automatic `--help` flag handling. Developers must manually implement help display logic.

fix

Implement custom help message display using standard Node.js I/O, as shown in the synopsis example in the README.

affects: >=1.0.0

gotchaArgument values must be separated by an equals sign (e.g., `--foo=bar`). Space separation (`--foo bar`) is not supported and will treat 'bar' as a separate positional argument.

fix

Ensure all option values are assigned using the `--key=value` syntax.

affects: >=1.0.0

gotchaParameter key names cannot contain the `.` character directly, as it is used internally. The `-` character is interpreted as a nesting delimiter (e.g., `--foo-bar` creates `{foo: {bar: ...}}`). To use `-` or `=` as part of a literal key name, they must be URL-encoded (`%2D`, `%3D`).

fix

Avoid `.` in key names. For literal `-` or `=`, use URL encoding if truly necessary, but generally prefer keys without these special characters or adjust your expected object structure for hyphens.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: argv is not a function

Attempting to use named import syntax (e.g., `import { argv } from 'process.argv'`) for a package that provides a default export.

fix

Use a default import: `import argv from 'process.argv';` in ESM/TypeScript or `const argv = require('process.argv');` in CommonJS.

My argument `--foo bar` isn't parsing 'bar' as a value, it's a positional argument.

The library does not support space-separated argument values. 'bar' is treated as a separate positional argument.

fix

Ensure all argument values are assigned using the equals sign: `--foo=bar`.

The configuration object doesn't contain a property when I use `--my.option=value`

The `.` character is a special character and is not available in key names; it can lead to unexpected parsing behavior or be ignored.

fix

Avoid using `.` in argument key names. Consider using hyphens (`--my-option`) which will map to nested objects (`{ my: { option: value } }`).

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/kawanet/process.argv ↗

packagehttps://www.npmjs.com/package/process.argv ↗