{"id":12821,"library":"arg","title":"Arg CLI Argument Parser","description":"arg is a minimalist, unopinionated command-line argument parser for Node.js applications. It focuses on providing a straightforward API for defining and parsing CLI options, including type conversion (String, Number, Boolean, custom functions), flag counting (e.g., `--verbose -vvv`), and aliasing. The current stable version is 5.0.2, with recent patch releases addressing type fixes and dependency updates, while major releases are infrequent but cautious, aiming for minimal disruption. It prioritizes simplicity and direct mapping of arguments to values, leaving validation and requirement checking to the application layer. This makes it suitable for projects needing a lightweight parsing solution without bundled opinionated features common in larger CLI frameworks.","status":"active","version":"5.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/vercel/arg","tags":["javascript","typescript"],"install":[{"cmd":"npm install arg","lang":"bash","label":"npm"},{"cmd":"yarn add arg","lang":"bash","label":"yarn"},{"cmd":"pnpm add arg","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM is preferred in modern Node.js. CommonJS `require` is also supported for older environments.","wrong":"const arg = require('arg');","symbol":"arg","correct":"import arg from 'arg';"},{"note":"Used as a type function within the spec object to count flag occurrences (e.g., -v, -vv, -vvv).","symbol":"arg.COUNT","correct":"import arg from 'arg';\n// arg.COUNT"},{"note":"A helper to mark a custom type handler as a boolean-like flag that does not consume a value.","symbol":"arg.flag","correct":"import arg from 'arg';\n// arg.flag(myHandler)"},{"note":"Exported as a named export since v5.0.0 for type checking errors thrown by `arg`.","wrong":"import arg from 'arg';\n// new arg.ArgError(...)","symbol":"ArgError","correct":"import { ArgError } from 'arg';"}],"quickstart":{"code":"import arg from 'arg';\n\ntype Args = {\n  '--help': boolean;\n  '--version': boolean;\n  '--verbose': number;\n  '--port': number;\n  '--name': string;\n  '--tag': string[];\n  '-v': string;\n  '-n': string;\n  '--label': string;\n  _?: string[];\n};\n\ntry {\n  const args = arg<Args>(\n    {\n      '--help': Boolean,\n      '--version': Boolean,\n      '--verbose': arg.COUNT,\n      '--port': Number,\n      '--name': String,\n      '--tag': [String],\n      '-v': '--verbose',\n      '-n': '--name',\n      '--label': '--name'\n    },\n    {\n      argv: process.argv.slice(2), // Defaults to process.argv.slice(2)\n      permissive: false,\n      stopAtPositional: false\n    }\n  );\n\n  if (args['--help']) {\n    console.log('Usage: my-cli [--help] [--version] [--verbose] [--port <num>] [--name <str>] [--tag <str>...]');\n    process.exit(0);\n  }\n\n  console.log('Parsed arguments:', args);\n  console.log('Positional arguments (_):', args._);\n  console.log('Verbose level:', args['--verbose']);\n  console.log('Port:', args['--port']);\n  console.log('Name:', args['--name']);\n  console.log('Tags:', args['--tag']);\n} catch (e: any) {\n  if (e.code === 'ARG_UNKNOWN_OPTION') {\n    console.error(`Error: ${e.message}`);\n    process.exit(1);\n  } else if (e.code === 'ARG_MISSING_VALUE') {\n    console.error(`Error: ${e.message}`);\n    process.exit(1);\n  } else {\n    console.error('An unexpected error occurred:', e);\n    process.exit(1);\n  }\n}","lang":"typescript","description":"Demonstrates basic setup with type definitions, option parsing (including counts and arrays), aliases, and basic error handling."},"warnings":[{"fix":"Update error handling logic to check `e.code` for specific error types (e.g., 'ARG_UNKNOWN_OPTION') or `e instanceof ArgError` for general `arg`-related errors.","message":"Since v5.0.0, all errors thrown by `arg` are now instances of `require('arg').ArgError` (or `import { ArgError } from 'arg'`). If your codebase checked `error.name` or `error.constructor` for specific error types, you will need to update these checks to use `ArgError`.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure all keys in your argument specification object (the first argument to `arg()`) are properly prefixed with one or two hyphens.","message":"Starting with v3.0.0, all properties defined in the argument specification object must begin with a hyphen (e.g., `--foo`, `-b`). Specifying a key without a hyphen (e.g., `foo: String`) will result in an error.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use `String`, `Number`, or a custom type function for options that require a value. Only use `Boolean`, `[Boolean]`, or `arg.flag()` for options that are presence-based switches.","message":"Boolean and `[Boolean]` types, along with `arg.flag()`, are treated as 'flags'. This means they do not consume the subsequent command-line argument as their value. If you expect a value after a boolean flag, it will be treated as a positional argument or another option.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Access `parsedArgs._` to retrieve any non-option arguments. Remember that `_` is always an array, even if empty.","message":"All unconsumed command-line arguments (positional arguments) are collected into an array assigned to the `_` key in the returned object. If your application expects positional arguments, you must explicitly handle this `_` array.","severity":"gotcha","affected_versions":">=0.2.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change the import statement to `import arg from 'arg';` and run your script as an ES module.","cause":"Attempting to use `const arg = require('arg');` in a JavaScript module that is treated as an ES module (e.g., in a package with `\"type\": \"module\"` or a `.mjs` file).","error":"ReferenceError: require is not defined"},{"fix":"Define `--some-undefined-option` in the `arg` specification object, or set `permissive: true` in the options object if you want to allow unknown options (they will be added to `_`).","cause":"The command-line option `--some-undefined-option` was passed but is not defined in the `arg` specification object, and `permissive: false` is either explicitly set or is the default.","error":"Error: Unknown or unexpected option: --some-undefined-option"},{"fix":"Ensure that options expecting values are followed by a value (e.g., `--port 8080` or `--port=8080`). If the option should be a flag without a value, change its type to `Boolean` or use `arg.COUNT` or `arg.flag()`.","cause":"An option was defined with a type that expects a value (e.g., `Number`, `String`), but no value was provided for that option on the command line.","error":"Error: Argument is missing for --option-with-value"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null}