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.
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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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.
const getArgs = require('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(...)`.
import * as getarg from 'getarg';
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.");
}
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.