{"id":13722,"library":"options-parser","title":"Command Line Options Parser","description":"options-parser is a lightweight, full-featured command-line argument parser for Node.js, designed with no external dependencies for a minimal footprint. The current stable version is 0.4.0, indicating it's still in active development, likely with a focus on stability before a 1.0 release. Its key differentiators include built-in type validation for common types (like files), automatic help screen generation with customizable formatting, and robust handling of multi-value options and default values. It provides a structured way to define expected command-line flags and arguments, distinguishing between required, optional, and flag-only parameters, making it suitable for scripting and CLI tool development in Node.js environments.","status":"active","version":"0.4.0","language":"javascript","source_language":"en","source_url":"http://github.com/janus-toendering/options-parser","tags":["javascript","getopt","arguments","options","command-line","option parser"],"install":[{"cmd":"npm install options-parser","lang":"bash","label":"npm"},{"cmd":"yarn add options-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add options-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is primarily CommonJS. Direct ESM import (`import options from 'options-parser';`) will not work without an appropriate wrapper or bundler configuration, or Node.js's CJS-to-ESM interop in some cases. The recommended approach for Node.js scripts is `require`.","wrong":"import options from 'options-parser';","symbol":"options","correct":"const options = require('options-parser');"},{"note":"The `parse` function is a method on the `options` object returned by `require`. It is not a named export. Ensure the `options` module is properly imported first.","wrong":"import { parse } from 'options-parser'; parse(optsConfig, argv);","symbol":"options.parse","correct":"const result = options.parse(optsConfig, argv);"},{"note":"`options.type` provides built-in type validation functions. It is accessed as a property of the main `options` object after initial `require`. For complex types, its properties are chained.","wrong":"const typeValidation = require('options-parser').type.file.open.write();","symbol":"options.type","correct":"const typeValidation = options.type.file.open.write();"},{"note":"The `help` function for generating help screens is also a method on the `options` object, not a direct named export.","wrong":"const { help } = require('options-parser'); help(optsConfig, helpOptions);","symbol":"options.help","correct":"options.help(optsConfig, helpOptions);"}],"quickstart":{"code":"const options = require('options-parser');\n\n// Define your command-line options structure\nconst optsConfig = {\n  user:  { required: true, help: 'Specify the user name for authentication.' },\n  all:   { short: 'a', flag: true, help: 'Process all available items (boolean flag).' },\n  host:  { short: 'h', default: 'localhost', help: 'Target host address for connection.' },\n  input: { short: 'i', multi: true, help: 'Input file paths (can be specified multiple times).' },\n  r:     { flag: true, help: 'Enable recursive mode for file operations.' },\n  db:    { default: 'test', help: 'Database name to connect to, defaults to \\'test\\'.' },\n  out:   { short: 'o', type: options.type.file.open.write(), help: 'Output file path with write access.' }\n};\n\n// Simulate command line arguments for demonstration purposes.\n// In a real application, this would typically be `process.argv.slice(2)`.\nconst simulatedArgv = [\n  '--user=joe',\n  '-a',\n  '--host',\n  'www.example.com',\n  'output.txt',\n  '-i',\n  'file1.txt',\n  '--input',\n  'file2.txt',\n  '-o',\n  'out.txt'\n];\n\n// Parse the arguments based on the defined configuration\nconst result = options.parse(optsConfig, simulatedArgv);\n\nconsole.log('--- Parsed Options and Arguments ---');\nconsole.log(JSON.stringify(result, null, 2));\n\n// Generate and log the help screen based on the same configuration\nconsole.log('\\n--- Generated Help Screen ---');\noptions.help(optsConfig, { output: console.log, columns: 80, paddingLeft: 2 });\n","lang":"javascript","description":"This quickstart demonstrates how to define a comprehensive set of command-line options including required fields, flags, default values, multi-value options, and type validation. It then parses a simulated argument array, logs the resulting structured data, and showcases the package's ability to automatically generate a formatted help screen."},"warnings":[{"fix":"Pass an `error` callback function as the second or third argument to `options.parse(opts, argv?, error?)` to handle errors programmatically, e.g., `options.parse(opts, (err) => console.error(err.message));`.","message":"When `options.parse()` is called without an `error` callback, any parsing errors (e.g., missing required options, invalid types) will cause an exception to be thrown, terminating the process. This default behavior might not be suitable for all applications.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure logical consistency in option definitions. For flags, omit `default`. For required options, `default` should only be considered if the 'required' state implies a non-null default, which can be confusing. Typically, remove `default` from `required: true` options.","message":"The `default` option should not be used in conjunction with `required: true` or `flag: true`. A default value implies the option is not strictly required, and `flag: true` options do not take values, rendering a default value meaningless for them.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always explicitly define `flag: true` or `flag: false` for options, especially when using `showHelp`, to ensure the parser behaves as expected regarding value expectations.","message":"If the `showHelp: true` option is defined for a specific flag, and `flag` is not explicitly set in the option definition, `options-parser` will implicitly set `flag: true` for that option. This can lead to unexpected behavior if you intended the option to take a value.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Consult the `options-parser` GitHub repository for release notes and changelogs before upgrading to new minor versions (e.g., 0.4.x to 0.5.x) to identify and adapt to any potential API changes.","message":"As a package still under version 1.0.0 (currently 0.4.0), API surfaces, especially related to type validation (`options.type`) or the structure of option definitions, might undergo breaking changes in future minor versions without strictly adhering to semantic versioning. Always review release notes when upgrading.","severity":"breaking","affected_versions":"<1.0.0"}],"env_vars":null,"search_vec":"'0.4.0':35 '1.0':51 'activ':41 'argument':17,98,122 'automat':67 'built':58 'built-in':57 'cli':114 'command':1,15,94,125 'command-lin':14,93,124 'common':63 'current':31 'customiz':72 'default':83 'defin':91 'depend':25 'design':21 'develop':42,116 'differenti':55 'distinguish':99 'environ':119 'expect':92 'extern':24 'featur':13 'file':66 'flag':96,105 'flag-on':104 'focus':46 'footprint':29 'format':73 'full':12 'full-featur':11 'generat':70 'getopt':121 'handl':76 'help':68 'includ':56 'indic':36 'javascript':120 'key':54 'lightweight':10 'like':43,65 'line':2,16,95,126 'make':108 'minim':28 'multi':79 'multi-valu':78 'node.js':20,118 'option':3,6,81,102,123,127 'options-pars':5 'paramet':107 'parser':4,7,18,128 'provid':86 'releas':52 'requir':101 'robust':75 'screen':69 'script':112 'stabil':48 'stabl':32 'still':39 'structur':88 'suitabl':110 'tool':115 'type':60,64 'valid':61 'valu':80,84 'version':33 'way':89","created_at":"2026-04-20T01:55:57.958385+00:00","updated_at":"2026-04-20T01:55:57.958385+00:00","problems":[{"fix":"Add `const options = require('options-parser');` at the top of your file to import the module.","cause":"The `options` variable was not properly initialized via `require('options-parser')` before being used.","error":"ReferenceError: options is not defined"},{"fix":"Ensure you are using `const options = require('options-parser');` and accessing `options.parse` as a method on the `options` object.","cause":"This error typically occurs when attempting to use ESM `import` syntax or destructuring assignment with a CommonJS module, or if the `options` variable was not assigned the correct module export.","error":"TypeError: options.parse is not a function"},{"fix":"Supply the missing required option in the command line (e.g., `--user=yourname`) or adjust your option definition if it's not truly required for all use cases.","cause":"An option defined with `required: true` in your configuration was not provided in the command-line arguments when `options.parse()` was called.","error":"Option 'user' is required but not present"},{"fix":"Either define the `unrecognized-flag` option in your `opts` configuration object, or ensure that only expected and defined options are passed on the command line.","cause":"A command-line option was provided (e.g., `--unrecognized-flag`) that is not defined in the `opts` object passed to `options.parse()`.","error":"Unknown option: --unrecognized-flag"}],"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/janus-toendering/options-parser","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/options-parser","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"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}}