{"id":13230,"library":"getarg","title":"Lightweight CLI Argument Parser","description":"getarg is a lightweight and fast command-line argument parser designed for Node.js applications, currently at version 0.0.5. It focuses on providing a simple API for defining, parsing, and validating CLI arguments, including support for required parameters, basic type enforcement (string, number, json, any), aliases, custom help messages, and inter-argument dependencies. Unlike more comprehensive CLI frameworks such as Yargs or Commander, `getarg` prioritizes minimalism and directness, making it suitable for smaller scripts or cases where extensive feature sets are not required. As a pre-1.0 release, its API might still evolve, though the core functionality is designed for quick integration into Node.js projects requiring basic argument handling.","status":"active","version":"0.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/el1s7/getarg","tags":["javascript","darg","getArgs","get-arg","argv","parser","cli","parameters","yarg"],"install":[{"cmd":"npm install getarg","lang":"bash","label":"npm"},{"cmd":"yarn add getarg","lang":"bash","label":"yarn"},{"cmd":"pnpm add getarg","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary argument parsing function `getArgs` is exported as a default export in ES Modules. Using named import syntax for it will result in 'undefined' or a runtime error.","wrong":"import { getArgs } from 'getarg';","symbol":"getArgs","correct":"import getArgs from 'getarg';"},{"note":"For CommonJS modules (e.g., in older Node.js projects or when `type: module` is not set in package.json), use `require()` to import the function. Direct ESM import syntax will not work in CJS environments without transpilation.","wrong":"import getArgs from 'getarg';","symbol":"getArgs","correct":"const getArgs = require('getarg');"},{"note":"While technically possible to import as a namespace, `getarg` primarily offers a default export. Importing as `* as getarg` will yield an object like `{ default: [Function: getArgs] }`, requiring subsequent calls to be `getarg.default(...)`.","wrong":"import getarg from 'getarg';","symbol":"* as getarg","correct":"import * as getarg from 'getarg';"}],"quickstart":{"code":"import getArgs from 'getarg';\n\n// Define expected arguments and their validation rules\nconst args = getArgs({\n    file: {\n        required: true,\n        type: \"string\",\n        help: \"Path to the input file to be processed.\",\n        requires: ['output'], // 'output' must also be present if 'file' is used\n        alias: \"f\"\n    },\n    output: {\n        help: \"Path where the processed output will be saved.\",\n        required: true,\n        type: \"string\",\n        alias: \"o\"\n    },\n    verbose: {\n        type: \"boolean\",\n        help: \"Enable verbose logging during execution.\",\n        default: false,\n        alias: \"v\"\n    }\n}, {\n    usage: \"Usage: node quickstart.js [--file <path>] [--output <path>] [-v]\" // Customize the help header\n});\n\n// If getarg didn't exit due to validation errors, we can proceed.\n// It will typically exit and print help/errors for invalid input.\nconsole.log(\"Parsed CLI Arguments:\");\nconsole.log(JSON.stringify(args, null, 2));\n\nif (args.file && args.output) {\n    console.log(`\\nStarting process with input '${args.file}' and output '${args.output}'.`);\n    if (args.verbose) {\n        console.log(\"Verbose logging is active.\");\n    }\n    // Simulate an operation with the parsed arguments\n    console.log(\"Operation simulated successfully.\");\n} else {\n    // This else block might only be reachable if a specific arg definition allows it\n    // or if getarg is configured not to exit on validation failure (not shown here).\n    // For typical usage, getarg exits before reaching here if required args are missing.\n    console.log(\"\\nNot all required arguments were provided or valid. getarg might have already displayed help or an error.\");\n}","lang":"javascript","description":"This quickstart demonstrates how to define required string arguments with aliases and inter-dependencies, add a boolean flag, and how the parser processes valid inputs, showing the structured output. It also implicitly highlights the built-in help display and validation behavior."},"warnings":[{"fix":"Always pin to exact versions (e.g., `\"getarg\": \"0.0.5\"`) and review release notes for updates.","message":"As a package in early development (v0.0.5), `getarg`'s API is not yet stable. Breaking changes may occur in minor or patch releases prior to reaching a 1.0.0 stable version.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Be aware that invalid input will terminate your script. Consider wrapper functions or alternative parsers if programmatic error handling is critical.","message":"`getarg` handles validation errors and help display by printing messages directly to `stdout`/`stderr` and then exiting the Node.js process. This behavior is opinionated and might prevent custom error handling or integration into larger applications that expect to catch and process argument parsing errors programmatically.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Evaluate if `getarg`'s capabilities meet your project's specific CLI requirements. For complex CLI structures, consider libraries like `commander` or `yargs`.","message":"`getarg` offers a focused feature set primarily for basic argument parsing and validation. It lacks advanced features common in other CLI libraries, such as support for subcommands (`git commit` vs `git push`), extensive type coercions beyond basic primitives, or custom validators.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Implement additional post-parsing logic to validate complex inter-argument dependencies or value-based conditions.","message":"The `requires` option for argument dependencies only checks for the *presence* of other parameters, not their values or types. For example, if `paramA` requires `paramB`, `getarg` will only ensure `paramB` exists, not that it has a specific value or is of a particular format.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Perform manual type conversion and validation after `getArgs` has processed the input, especially for array inputs or custom data types.","message":"Type validation is limited to 'string', 'number', 'json', and 'any'. There is no built-in support for array types, enums, custom parsing functions, or complex object structures beyond basic JSON parsing.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure that parameters expecting a string value are provided with one. For instance, `node cli.js --file \"./input.txt\"` or `-f value`.","cause":"A parameter defined with `type: \"string\"` (or implicitly, as string is default for value-accepting parameters) was provided without a value, or with a value that `getarg` did not interpret as a string (e.g., a boolean flag without a value).","error":"[!] The paramater '--file' is not a string."},{"fix":"Provide a valid integer or floating-point number for parameters expecting a numeric type, e.g., `node cli.js --count 123`.","cause":"A parameter explicitly defined with `type: \"number\"` received a non-numeric value from the command line.","error":"[!] The parameter '--count' is not a number."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}