{"id":13431226,"url":"https://github.com/vercel/arg","last_synced_at":"2025-04-29T14:33:56.993Z","repository":{"id":37443661,"uuid":"100829255","full_name":"vercel/arg","owner":"vercel","description":"Simple argument parsing","archived":false,"fork":false,"pushed_at":"2024-07-18T14:08:05.000Z","size":328,"stargazers_count":1276,"open_issues_count":17,"forks_count":53,"subscribers_count":61,"default_branch":"main","last_synced_at":"2025-04-24T04:37:36.302Z","etag":null,"topics":["argument","argv","cli","command","parser"],"latest_commit_sha":null,"homepage":"https://npmjs.com/arg","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/vercel.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-20T00:38:19.000Z","updated_at":"2025-04-23T18:30:03.000Z","dependencies_parsed_at":"2024-09-23T10:56:05.418Z","dependency_job_id":"0a121d0f-9f55-4976-904e-934b87477365","html_url":"https://github.com/vercel/arg","commit_stats":{"total_commits":61,"total_committers":22,"mean_commits":2.772727272727273,"dds":0.819672131147541,"last_synced_commit":"07b9cadc447bfeddbe9a6b252ee1e6671833ba23"},"previous_names":["zeit/arg","zeit/zarg"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel%2Farg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel%2Farg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel%2Farg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel%2Farg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vercel","download_url":"https://codeload.github.com/vercel/arg/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251519510,"owners_count":21602342,"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":["argument","argv","cli","command","parser"],"created_at":"2024-07-31T02:01:01.477Z","updated_at":"2025-04-29T14:33:56.974Z","avatar_url":"https://github.com/vercel.png","language":"JavaScript","readme":"# Arg\n\n`arg` is an unopinionated, no-frills CLI argument parser.\n\n## Installation\n\n```bash\nnpm install arg\n```\n\n## Usage\n\n`arg()` takes either 1 or 2 arguments:\n\n1. Command line specification object (see below)\n2. Parse options (_Optional_, defaults to `{permissive: false, argv: process.argv.slice(2), stopAtPositional: false}`)\n\nIt returns an object with any values present on the command-line (missing options are thus\nmissing from the resulting object). Arg performs no validation/requirement checking - we\nleave that up to the application.\n\nAll parameters that aren't consumed by options (commonly referred to as \"extra\" parameters)\nare added to `result._`, which is _always_ an array (even if no extra parameters are passed,\nin which case an empty array is returned).\n\n```javascript\nconst arg = require('arg');\n\n// `options` is an optional parameter\nconst args = arg(\n\tspec,\n\t(options = { permissive: false, argv: process.argv.slice(2) })\n);\n```\n\nFor example:\n\n```console\n$ node ./hello.js --verbose -vvv --port=1234 -n 'My name' foo bar --tag qux --tag=qix -- --foobar\n```\n\n```javascript\n// hello.js\nconst arg = require('arg');\n\nconst args = arg({\n\t// Types\n\t'--help': Boolean,\n\t'--version': Boolean,\n\t'--verbose': arg.COUNT, // Counts the number of times --verbose is passed\n\t'--port': Number, // --port \u003cnumber\u003e or --port=\u003cnumber\u003e\n\t'--name': String, // --name \u003cstring\u003e or --name=\u003cstring\u003e\n\t'--tag': [String], // --tag \u003cstring\u003e or --tag=\u003cstring\u003e\n\n\t// Aliases\n\t'-v': '--verbose',\n\t'-n': '--name', // -n \u003cstring\u003e; result is stored in --name\n\t'--label': '--name' // --label \u003cstring\u003e or --label=\u003cstring\u003e;\n\t//     result is stored in --name\n});\n\nconsole.log(args);\n/*\n{\n\t_: [\"foo\", \"bar\", \"--foobar\"],\n\t'--port': 1234,\n\t'--verbose': 4,\n\t'--name': \"My name\",\n\t'--tag': [\"qux\", \"qix\"]\n}\n*/\n```\n\nThe values for each key=\u0026gt;value pair is either a type (function or [function]) or a string (indicating an alias).\n\n- In the case of a function, the string value of the argument's value is passed to it,\n  and the return value is used as the ultimate value.\n\n- In the case of an array, the only element _must_ be a type function. Array types indicate\n  that the argument may be passed multiple times, and as such the resulting value in the returned\n  object is an array with all of the values that were passed using the specified flag.\n\n- In the case of a string, an alias is established. If a flag is passed that matches the _key_,\n  then the _value_ is substituted in its place.\n\nType functions are passed three arguments:\n\n1. The parameter value (always a string)\n2. The parameter name (e.g. `--label`)\n3. The previous value for the destination (useful for reduce-like operations or for supporting `-v` multiple times, etc.)\n\nThis means the built-in `String`, `Number`, and `Boolean` type constructors \"just work\" as type functions.\n\nNote that `Boolean` and `[Boolean]` have special treatment - an option argument is _not_ consumed or passed, but instead `true` is\nreturned. These options are called \"flags\".\n\nFor custom handlers that wish to behave as flags, you may pass the function through `arg.flag()`:\n\n```javascript\nconst arg = require('arg');\n\nconst argv = [\n\t'--foo',\n\t'bar',\n\t'-ff',\n\t'baz',\n\t'--foo',\n\t'--foo',\n\t'qux',\n\t'-fff',\n\t'qix'\n];\n\nfunction myHandler(value, argName, previousValue) {\n\t/* `value` is always `true` */\n\treturn 'na ' + (previousValue || 'batman!');\n}\n\nconst args = arg(\n\t{\n\t\t'--foo': arg.flag(myHandler),\n\t\t'-f': '--foo'\n\t},\n\t{\n\t\targv\n\t}\n);\n\nconsole.log(args);\n/*\n{\n\t_: ['bar', 'baz', 'qux', 'qix'],\n\t'--foo': 'na na na na na na na na batman!'\n}\n*/\n```\n\nAs well, `arg` supplies a helper argument handler called `arg.COUNT`, which equivalent to a `[Boolean]` argument's `.length`\nproperty - effectively counting the number of times the boolean flag, denoted by the key, is passed on the command line..\nFor example, this is how you could implement `ssh`'s multiple levels of verbosity (`-vvvv` being the most verbose).\n\n```javascript\nconst arg = require('arg');\n\nconst argv = ['-AAAA', '-BBBB'];\n\nconst args = arg(\n\t{\n\t\t'-A': arg.COUNT,\n\t\t'-B': [Boolean]\n\t},\n\t{\n\t\targv\n\t}\n);\n\nconsole.log(args);\n/*\n{\n\t_: [],\n\t'-A': 4,\n\t'-B': [true, true, true, true]\n}\n*/\n```\n\n### Options\n\nIf a second parameter is specified and is an object, it specifies parsing options to modify the behavior of `arg()`.\n\n#### `argv`\n\nIf you have already sliced or generated a number of raw arguments to be parsed (as opposed to letting `arg`\nslice them from `process.argv`) you may specify them in the `argv` option.\n\nFor example:\n\n```javascript\nconst args = arg(\n\t{\n\t\t'--foo': String\n\t},\n\t{\n\t\targv: ['hello', '--foo', 'world']\n\t}\n);\n```\n\nresults in:\n\n```javascript\nconst args = {\n\t_: ['hello'],\n\t'--foo': 'world'\n};\n```\n\n#### `permissive`\n\nWhen `permissive` set to `true`, `arg` will push any unknown arguments\nonto the \"extra\" argument array (`result._`) instead of throwing an error about\nan unknown flag.\n\nFor example:\n\n```javascript\nconst arg = require('arg');\n\nconst argv = [\n\t'--foo',\n\t'hello',\n\t'--qux',\n\t'qix',\n\t'--bar',\n\t'12345',\n\t'hello again'\n];\n\nconst args = arg(\n\t{\n\t\t'--foo': String,\n\t\t'--bar': Number\n\t},\n\t{\n\t\targv,\n\t\tpermissive: true\n\t}\n);\n```\n\nresults in:\n\n```javascript\nconst args = {\n\t_: ['--qux', 'qix', 'hello again'],\n\t'--foo': 'hello',\n\t'--bar': 12345\n};\n```\n\n#### `stopAtPositional`\n\nWhen `stopAtPositional` is set to `true`, `arg` will halt parsing at the first\npositional argument.\n\nFor example:\n\n```javascript\nconst arg = require('arg');\n\nconst argv = ['--foo', 'hello', '--bar'];\n\nconst args = arg(\n\t{\n\t\t'--foo': Boolean,\n\t\t'--bar': Boolean\n\t},\n\t{\n\t\targv,\n\t\tstopAtPositional: true\n\t}\n);\n```\n\nresults in:\n\n```javascript\nconst args = {\n\t_: ['hello', '--bar'],\n\t'--foo': true\n};\n```\n\n### Errors\n\nSome errors that `arg` throws provide a `.code` property in order to aid in recovering from user error, or to\ndifferentiate between user error and developer error (bug).\n\n##### ARG_UNKNOWN_OPTION\n\nIf an unknown option (not defined in the spec object) is passed, an error with code `ARG_UNKNOWN_OPTION` will be thrown:\n\n```js\n// cli.js\ntry {\n\trequire('arg')({ '--hi': String });\n} catch (err) {\n\tif (err.code === 'ARG_UNKNOWN_OPTION') {\n\t\tconsole.log(err.message);\n\t} else {\n\t\tthrow err;\n\t}\n}\n```\n\n```shell\nnode cli.js --extraneous true\nUnknown or unexpected option: --extraneous\n```\n\n# FAQ\n\nA few questions and answers that have been asked before:\n\n### How do I require an argument with `arg`?\n\nDo the assertion yourself, such as:\n\n```javascript\nconst args = arg({ '--name': String });\n\nif (!args['--name']) throw new Error('missing required argument: --name');\n```\n\n# License\n\nReleased under the [MIT License](LICENSE.md).\n","funding_links":[],"categories":["JavaScript","Repository","cli","Packages"],"sub_categories":["Command-line Utilities"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvercel%2Farg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvercel%2Farg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvercel%2Farg/lists"}