getarg

library0.0.5jsnpmunverified

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.

npm install getarg

github ↗package ↗

INSTALL

IMPORT

SIG · GETARG

getarg

javascriptv0.0.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

getArgs

✓ import getArgs from 'getarg';

✗ import { getArgs } from 'getarg';

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.

getArgs

✓ const getArgs = require('getarg');

✗ import getArgs from 'getarg';

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.

* as getarg

✓ import * as getarg from 'getarg';

✗ import getarg from 'getarg';

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(...)`.

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.

import getArgs from 'getarg'; // Define expected arguments and their validation rules const args = getArgs({ file: { required: true, type: "string", help: "Path to the input file to be processed.", requires: ['output'], // 'output' must also be present if 'file' is used alias: "f" }, output: { help: "Path where the processed output will be saved.", required: true, type: "string", alias: "o" }, verbose: { type: "boolean", help: "Enable verbose logging during execution.", default: false, alias: "v" } }, { usage: "Usage: node quickstart.js [--file <path>] [--output <path>] [-v]" // Customize the help header }); // If getarg didn't exit due to validation errors, we can proceed. // It will typically exit and print help/errors for invalid input. console.log("Parsed CLI Arguments:"); console.log(JSON.stringify(args, null, 2)); if (args.file && args.output) { console.log(`\nStarting process with input '${args.file}' and output '${args.output}'.`); if (args.verbose) { console.log("Verbose logging is active."); } // Simulate an operation with the parsed arguments console.log("Operation simulated successfully."); } else { // This else block might only be reachable if a specific arg definition allows it // or if getarg is configured not to exit on validation failure (not shown here). // For typical usage, getarg exits before reaching here if required args are missing. console.log("\nNot all required arguments were provided or valid. getarg might have already displayed help or an error."); }

Debug

Known issues

breakingAs 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.

fix

Always pin to exact versions (e.g., `"getarg": "0.0.5"`) and review release notes for updates.

affects: <1.0.0

gotcha`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.

fix

Be aware that invalid input will terminate your script. Consider wrapper functions or alternative parsers if programmatic error handling is critical.

affects: >=0.0.1

gotcha`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.

fix

Evaluate if `getarg`'s capabilities meet your project's specific CLI requirements. For complex CLI structures, consider libraries like `commander` or `yargs`.

affects: >=0.0.1

gotchaThe `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.

fix

Implement additional post-parsing logic to validate complex inter-argument dependencies or value-based conditions.

affects: >=0.0.1

gotchaType 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.

fix

Perform manual type conversion and validation after `getArgs` has processed the input, especially for array inputs or custom data types.

affects: >=0.0.1

Errors

Common errors & fixes

[!] The paramater '--file' is not a string.

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).

fix

Ensure that parameters expecting a string value are provided with one. For instance, `node cli.js --file "./input.txt"` or `-f value`.

[!] The parameter '--count' is not a number.

A parameter explicitly defined with `type: "number"` received a non-numeric value from the command line.

fix

Provide a valid integer or floating-point number for parameters expecting a numeric type, e.g., `node cli.js --count 123`.

Upgrade

Version history

0.0.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/el1s7/getarg ↗

packagehttps://www.npmjs.com/package/getarg ↗