minargs

library2.1.0jsnpmunverified

minargs is a JavaScript argument parser designed for minimal configuration and assumptions. Currently at version 2.1.0, it provides a barebones approach to parsing command-line arguments without built-in usage messages, validation, type coercion, or strictness. Its core philosophy is to 'Bring Your Own Usage™️' and 'Bring Your Own Validation™️', making it highly flexible but requiring more boilerplate for complex applications. It maintains zero runtime dependencies and aims for consistent results, returning a structured object containing `args`, `positionals`, `remainder`, and `argv` for fine-grained control over parsed input. This library is suitable for projects where developers prefer explicit control over argument processing rather than relying on opinionated, feature-rich parsers, and requires Node.js versions `^12.13.0 || ^14.15.0 || >=16`.

devops

npm install minargs

github ↗package ↗

INSTALL

IMPORT

SIG · MINARGS

minargs

devopsjavascriptv2.1.0

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.

minargs

✓ import { minargs } from 'minargs';

✗ const minargs = require('minargs');

CommonJS `require` is also supported as shown in README examples, but ESM is standard for modern Node.js environments.

minargs

✓ const { minargs } = require('minargs');

✗ import minargs from 'minargs';

minargs is a named export; direct default import is not available.

ParsedArgs

✓ import type { ParsedArgs } from 'minargs';

Import TypeScript types for the returned object structure when using TypeScript.

Demonstrates basic argument parsing using `minargs`, showing how it separates named arguments, positional values, and a 'remainder' array after a bare `--` delimiter.

#!/usr/bin/env node // basic.js const { minargs } = require('minargs'); // Simulate the arguments that would typically follow 'node script.js' // For example, running from the command line: `node basic.js - --foo=bar -- --baz` const mockArgs = ['-', '--foo=bar', '--', '--baz']; // Parse the simulated arguments. In a real script, minargs() without arguments // would parse process.argv directly, slicing off the first two elements. const { args, positionals, remainder, argv } = minargs(mockArgs); console.log('Parsed Arguments:'); console.log(' args:', args); console.log(' positionals:', positionals); console.log(' remainder:', remainder); console.log(' argv (detailed parse data):', argv); /* Expected output for minargs(['-', '--foo=bar', '--', '--baz']): Parsed Arguments: args: { foo: [ 'bar' ] } positionals: [ '-' ] remainder: [ '--baz' ] argv (detailed parse data): [ { index: 0, type: 'positional', value: '-' }, { index: 1, type: 'argument', value: { name: 'foo', value: 'bar' } }, { index: 2, type: 'bare_delimiter', value: '--' }, { index: 3, type: 'positional', value: '--baz' } ] */ process.exit(0);

Debug

Known issues

gotchaminargs explicitly does not perform validation or type coercion. All argument values are returned as strings in arrays. Developers must implement their own validation and type conversion logic.

fix

Implement custom validation (e.g., using `Object.keys(args).filter(...)`) and type conversion (e.g., `Number(args.port[0])`) after parsing the arguments.

affects: >=1.0

gotchaThe `positionalValues` option defaults to `false`. This means that in `--foo bar`, `bar` will be treated as a positional argument rather than a value for `--foo`, unless `positionalValues: true` is explicitly set.

fix

If you expect bare flag definitions to consume the next token as their value, pass `{ positionalValues: true }` in the options object to `minargs()`.

affects: >=1.0

gotchaOnly single-character aliases defined in the `alias` option can be parsed as 'shorts' (e.g., `-f`). Multi-character aliases are treated as full arguments unless explicitly handled or aliased.

fix

Ensure that `alias` keys intended for short flag parsing are single characters. For multi-character aliases, treat them as full arguments or implement custom alias mapping.

affects: >=1.0

gotchaBy default, the `recursive` option is `false`. Parsing stops when a bare `--` marker is found, and all subsequent arguments are placed into the `remainder` array without further parsing.

fix

Set `recursive: true` in the options if you wish `minargs` to continue parsing arguments after a `--` marker. Otherwise, manually process the `remainder` array if you need to pass them to another process or parser.

affects: >=1.0

Errors

Common errors & fixes

TypeError: Cannot read property 'length' of undefined (or similar type-related errors when accessing argument values)

minargs returns all argument values as arrays of strings. Accessing `args.foo` directly might return `undefined` if `--foo` was not present, or an empty array `[]` if present without a value.

fix

Always check for existence and handle the array. Example: `const fooValue = args.foo ? args.foo[0] : undefined;` or `const count = Number(args.count?.[0] || '0');`.

Argument '--port' expected a number but received '8080' (string)

minargs does not perform automatic type coercion. All parsed values are strings.

fix

Explicitly convert parsed string values to the desired types. Example: `const port = Number(args.port?.[0]);` or `const verbose = args.verbose?.includes('') ?? false;`.

Command failed: Unknown flag --verbose, or missing required argument --input

minargs provides no built-in validation for known arguments or required parameters. All arguments are parsed without judgment.

fix

Implement custom validation logic against the `args` and `positionals` objects after parsing. Maintain a list of known arguments and check for their presence and format manually or with an external validation library.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/darcyclarke/minargs ↗

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