{"id":13812,"library":"process.argv","title":"Process.argv CLI Argument Parser","description":"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.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/kawanet/process.argv","tags":["javascript","cli","commander","options","typescript"],"install":[{"cmd":"npm install process.argv","lang":"bash","label":"npm"},{"cmd":"yarn add process.argv","lang":"bash","label":"yarn"},{"cmd":"pnpm add process.argv","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package exports a default function, not named exports, for ESM/TypeScript environments.","wrong":"import { argv } from 'process.argv'","symbol":"argv","correct":"import argv from 'process.argv'"},{"note":"CommonJS environments should use the default import pattern.","wrong":"const { argv } = require('process.argv')","symbol":"argv","correct":"const argv = require('process.argv')"},{"note":"The `argv` function expects an array of arguments, typically `process.argv.slice(2)` to exclude Node.js executable path and script path.","symbol":"processArgv","correct":"const processArgv = argv(process.argv.slice(2));"}],"quickstart":{"code":"import argv from 'process.argv';\n\ninterface Config {\n    foo: string;\n    bar: {\n        buz: string;\n    };\n    qux?: boolean;\n    '--'?: string[]; // To capture positional arguments\n}\n\n// Simulate process.argv for demonstration\nconst mockArgs = ['node', 'cli.js', '--foo=hello', '--bar-buz=world', 'file1.txt', 'file2.txt'];\n// In a real CLI, use: argv(process.argv.slice(2))\nconst processArgv = argv(mockArgs.slice(2));\n\nconst config = processArgv<Config>({\n    foo: 'defaultFoo',\n    bar: {\n        buz: 'defaultBuz'\n    },\n    qux: false\n});\n\nconsole.log('Parsed Configuration:', config);\nconsole.log('Foo:', config.foo); // Should be 'hello'\nconsole.log('Bar Buz:', config.bar.buz); // Should be 'world'\nconsole.log('Qux (default):', config.qux); // Should be false\n\n// Access positional arguments (e.g., file1.txt, file2.txt)\nconst positionalArgs = config['--'] || [];\nconsole.log('Positional Arguments:', positionalArgs);","lang":"typescript","description":"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."},"warnings":[{"fix":"Always use the full, long-form argument names (e.g., `--verbose` instead of `-v`).","message":"The parser does not support shortcut flag names (e.g., -f for --force); full option names like `--force` must always be used.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement custom help message display using standard Node.js I/O, as shown in the synopsis example in the README.","message":"The library does not provide built-in help message generation or automatic `--help` flag handling. Developers must manually implement help display logic.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure all option values are assigned using the `--key=value` syntax.","message":"Argument 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Parameter 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`).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.0.0':21 '2024':40 'abandon':50 'activ':42 'altern':59 'argument':3,12,85,93 'automat':100 'bar':89,110 'bar-buz':109 'built':76 'built-in':75 'buz':111 'cadenc':31 'ci':43 'cli':2,11,133,137 'command':63,138 'common':67 'config.bar.buz':114 'conveni':68 'copyright':36 'current':17 'design':116 'develop':127 'differenti':52 'e.g':73,87,108 'explicit':123 'extend':38 'f':74 'featur':57,134 'feature-rich':56 'flag':72 'foo':88 'footprint':121 'format':99 'generat':80 'github':33 'handl':101 'help':78 'higher':131 'higher-level':130 'hyphen':106 'implement':129 'indic':45 'instead':90 'intent':65 'javascript':136 'key':97,107 'level':132 'lightweight':8 'like':60 'logic':125 'mainten':47 'map':112 'messag':79 'minim':10 'nest':102 'node.js':15 'object':103 'omit':66 'ongo':46 'option':139 'packag':24 'pars':124 'parser':4,13 'philosophi':117 'priorit':118 'process':92 'process.argv':1,5 'rapid':29 'rather':48 'releas':30 'repositori':34 'requir':126 'rich':58 'separ':84 'shortcut':71 'show':35 'small':120 'space':83 'space-separ':82 'stabl':18 'strict':94 'structur':104 'typescript':140 'updat':37 'valu':86,98 'version':19 'workflow':44 'yarg':61","created_at":"2026-04-20T01:56:26.682496+00:00","updated_at":"2026-04-20T01:56:26.682496+00:00","problems":[{"fix":"Use a default import: `import argv from 'process.argv';` in ESM/TypeScript or `const argv = require('process.argv');` in CommonJS.","cause":"Attempting to use named import syntax (e.g., `import { argv } from 'process.argv'`) for a package that provides a default export.","error":"TypeError: argv is not a function"},{"fix":"Ensure all argument values are assigned using the equals sign: `--foo=bar`.","cause":"The library does not support space-separated argument values. 'bar' is treated as a separate positional argument.","error":"My argument `--foo bar` isn't parsing 'bar' as a value, it's a positional argument."},{"fix":"Avoid using `.` in argument key names. Consider using hyphens (`--my-option`) which will map to nested objects (`{ my: { option: value } }`).","cause":"The `.` character is a special character and is not available in key names; it can lead to unexpected parsing behavior or be ignored.","error":"The configuration object doesn't contain a property when I use `--my.option=value`"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/kawanet/process.argv","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/process.argv","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}