{"id":13464984,"url":"https://github.com/jorgebucaran/getopts","last_synced_at":"2025-05-14T22:08:11.976Z","repository":{"id":31728243,"uuid":"35294154","full_name":"jorgebucaran/getopts","owner":"jorgebucaran","description":"Node.js CLI options parser","archived":false,"fork":false,"pushed_at":"2021-02-15T19:11:58.000Z","size":247,"stargazers_count":635,"open_issues_count":6,"forks_count":22,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-24T14:28:02.386Z","etag":null,"topics":["argv","cli-parser","getopts","node"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jorgebucaran.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-08T18:04:48.000Z","updated_at":"2025-03-18T22:20:26.000Z","dependencies_parsed_at":"2022-07-19T03:02:20.526Z","dependency_job_id":null,"html_url":"https://github.com/jorgebucaran/getopts","commit_stats":null,"previous_names":["jorgebucaran/getopts","srcfile/getopts","joxji/getopts"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgebucaran%2Fgetopts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgebucaran%2Fgetopts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgebucaran%2Fgetopts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jorgebucaran%2Fgetopts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jorgebucaran","download_url":"https://codeload.github.com/jorgebucaran/getopts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252168188,"owners_count":21705219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["argv","cli-parser","getopts","node"],"created_at":"2024-07-31T14:00:54.089Z","updated_at":"2025-05-14T22:08:06.966Z","avatar_url":"https://github.com/jorgebucaran.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","node"],"sub_categories":[],"readme":"# Getopts\n\n\u003e Parse CLI arguments.\n\n- Lightweight drop-in replacement for `minimist` and clones.\n- Small (180 LOC), focused, no dependencies.\n- Up to [6x faster](#benchmarks) than alternatives!\n\nBreak up command-line arguments into key-value pairs for easy look-up and retrieval. Built upon [utility conventions](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02) that have been used for decades, Getopts sane defaults help you write CLI tools that look and feel like the real deal.\n\n```console\n$ example --type=module -o main.js *.{js,json}\n```\n\n```js\nimport getopts from \"getopts\"\n\nconst options = getopts(process.argv.slice(2), {\n  alias: {\n    output: [\"o\", \"f\"],\n    type: \"t\",\n  },\n})\n```\n\nThe result is an object populated with all the parsed arguments.\n\n```js\n{\n  _: [\"index.js\", \"package.json\"],\n  output: \"main.js\",\n  type: \"module\",\n  o: \"main.js\",\n  f: \"main.js\",\n  t: \"module\",\n}\n```\n\n## Installation\n\n```console\nnpm install getopts\n```\n\n## Parsing rules\n\n### Short options\n\nA short option consists of a `-` followed by a single alphabetic character. Multiple options can be grouped together without spaces. Short options are boolean by default unless followed by an [operand](#operand) (non-option) or if adjacent to any non-alphabetic characters:\n\n```js\ngetopts([\"-ab\", \"-c\"]) //=\u003e { _: [], a:true, b:true, c:true }\n```\n\n```js\ngetopts([\"-a\", \"alpha\"]) //=\u003e { _: [], a:\"alpha\" }\n```\n\n```js\ngetopts([\"-abc1\"]) //=\u003e { _: [], a:true, b:true, c:1 }\n```\n\nUse [`opts.string`](#optsstring) to parse an option as a string regardless.\n\n```js\ngetopts([\"-kF12\"], {\n  string: [\"k\"],\n}) //=\u003e { _: [], k:\"F12\" }\n```\n\nThe first operand following an option will be used as its value. Use [`opts.boolean`](#optsboolean) to specify that an option should be parsed as a boolean regardless, causing the following argument to be treated as an operand instead.\n\n```js\ngetopts([\"-a\", \"alpha\"], {\n  boolean: [\"a\"],\n}) //=\u003e { _: [\"alpha\"], a:true }\n```\n\nAny character listed in the ASCII table can be used as a short option if it's the first character after the dash.\n\n```js\ngetopts([\"-9\", \"-#10\", \"-%0.01\"]) //=\u003e { _:[], 9:true, #:10, %:0.01 }\n```\n\n### Long options\n\nA long option consists of a `--` followed by a name and a value separated by an `=`. Long options without a value are boolean by default.\n\n```js\ngetopts([\"--turbo\", \"--warp=10\"]) //=\u003e { _: [], turbo:true, warp:10 }\n```\n\n```js\ngetopts([\"--warp=e=mc^2\"]) //=\u003e { _: [], warp:\"e=mc^2\" }\n```\n\n```js\ngetopts([\"--@\", \"alpha\"]) //=\u003e { _: [], @:\"alpha\" }\n```\n\nNegated options start with `--no-` and are always `false`.\n\n```js\ngetopts([\"--no-turbo\"]) //=\u003e { _: [], turbo:false }\n```\n\n### Operands\n\nEvery non-option argument is an operand. Operands are saved to the `result._` operands array.\n\n```js\ngetopts([\"alpha\", \"-w9\", \"bravo\"]) //=\u003e { _: [\"alpha\", \"bravo\"], w:9 }\n```\n\n```js\ngetopts([\"--code=alpha\", \"bravo\"]) //=\u003e { _: [\"bravo\"], code:\"alpha\" }\n```\n\nEverything after a standalone `--` is an operand.\n\n```js\ngetopts([\"--alpha\", \"--\", \"--bravo\", \"--turbo\"]) //=\u003e { _:[\"--bravo\", \"--turbo\"], alpha:true }\n```\n\nA single `-` is also treated as an operand.\n\n```js\ngetopts([\"--turbo\", \"-\"]) //=\u003e { _:[\"-\"], turbo:true }\n```\n\n### Other\n\nOptions specified as boolean or string will be added to the result object as `false` or `\"\"` (even if missing from the arguments array).\n\n```js\ngetopts([], {\n  string: [\"a\"],\n  boolean: [\"b\"],\n}) //=\u003e { _:[], a:\"\", b:false }\n```\n\nRepeated options are stored as arrays with every value in order of appearance.\n\n```js\ngetopts([\"-x?alpha=bravo\", \"-x3.14\", \"-x\"] //=\u003e { _:[], a:[\"?alpha=bravo\", 3.14, true] }\n```\n\nA value may contain newlines or other control characters.\n\n```js\ngetopts([\"--text=top\\n\\tbottom\"]) //=\u003e { _:[], text:\"top\\n\\tbottom\" }\n```\n\n`=\"false\"` is converted to boolean by default.\n\n```js\ngetopts([\"--turbo=false\"]) //=\u003e { _:[], turbo:false }\n```\n\n## API\n\n### `getopts(argv, opts)`\n\nParse command-line arguments. Returns an object mapping argument names to their values.\n\n### `argv[]`\n\nAn array of arguments, usually [`process.argv`](https://nodejs.org/docs/latest/api/process.html#process_process_argv).\n\n### `opts.alias`\n\nAn object of option aliases. An alias can be a string or an array of strings. Aliases let you declare substitute names for an option, e.g., the short (abbreviated) and long (canonical) variations.\n\n```js\ngetopts([\"-t\"], {\n  alias: {\n    turbo: [\"t\", \"T\"],\n  },\n}) //=\u003e { _:[], t:true, T:true, turbo:true }\n```\n\n### `opts.boolean`\n\nAn array of options to parse as boolean. In the example below, `t` is parsed as a boolean, causing the following argument to be treated as an operand.\n\n```js\ngetopts([\"-t\", \"alpha\"], {\n  boolean: [\"t\"],\n}) //=\u003e { _:[\"alpha\"], t:true }\n```\n\n### `opts.string`\n\nAn array of flags to parse as strings. In the example below, `t` is parsed as a string, causing all adjacent characters to be treated as a single value and not as individual options.\n\n```js\ngetopts([\"-atabc\"], {\n  string: [\"t\"],\n}) //=\u003e { _:[], a:true, t:\"abc\" }\n```\n\n### `opts.default`\n\nAn object of default values for options not present in the arguments array.\n\n```js\ngetopts([\"--warp=10\"], {\n  default: {\n    warp: 15,\n    turbo: true,\n  },\n}) //=\u003e { _:[], warp:10, turbo:true }\n```\n\n### `opts.unknown()`\n\nWe call this function for each unknown option. Return `false` to discard the option. Unknown options are those that appear in the arguments array, but are not in `opts.string`, `opts.boolean`, `opts.default`, or `opts.alias`.\n\n```js\ngetopts([\"-abc\"], {\n  unknown: (option) =\u003e \"a\" === option,\n}) //=\u003e { _:[], a:true }\n```\n\n### `opts.stopEarly`\n\nA boolean property. If `true`, the operands array `_` will be populated with all the arguments after the first operand.\n\n```js\ngetopts([\"-w9\", \"alpha\", \"--turbo\", \"bravo\"], {\n  stopEarly: true,\n}) //=\u003e { _:[\"alpha\", \"--turbo\", \"bravo\"], w:9 }\n```\n\nThis property is useful when implementing sub-commands in a CLI.\n\n```js\nimport getopts from \"getopts\"\nimport { install, update, uninstall } from \"./commands.js\"\n\nconst options = getopts(process.argv.slice(2), {\n  stopEarly: true,\n})\n\nconst [command, subargv] = options._\n\nif (command === \"install\") {\n  install(subargv)\n} else if (command === \"update\") {\n  update(subargv)\n} else if (command === \"uninstall\") {\n  uninstall(subargv)\n}\n```\n\n## Benchmarks\n\n```console\nnpm --prefix bench start\n```\n\n## License\n\n[MIT](LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjorgebucaran%2Fgetopts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjorgebucaran%2Fgetopts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjorgebucaran%2Fgetopts/lists"}