package
minimum viable argument parser
npm install minargsGitHub-flavored package documentation.
Across all versions, last 30 days.
124,226 in 30 days
Runtime metadata.
Tagged topics.
Estimated unpacked size across 1 packages.
43.5 kB
Includes dependencies.
minargs is an argument parser with minimal configuration & assumptions. Argument parsing can take many shapes but the explicit goals of this library are as follows:
npm install minargsminargs([argv][, options])argv (Array)
process.argvalias (Object)
positionalValues (Boolean)
falserecursive (Boolean)
false-- marker is found{
args: {},
positionals: [],
remainder: [],
argv: []
}argsObject of canonical argument keys with corresponding Array of parsed String values--foo will return [""] (note the empty string by default)--foo=bar will return ["bar"]--foo bar will return ["bar"] when positionalValues is true
bar is treated as a positional & returned in positionals if positionalValues is falsepositionalsArray of parsed positional String valuesremainderArray of String values the follow the first bare -- when recursive is falseargvArray of Objects with corresponding indexs mapping back to the original process.argv or provided ArrayObjects also contain the value parsed & type (ie. "argument", "short", "positional" or "value")type "value" will only ever be defined -- in place of "positional" -- when positionalValues=trueString values or extending the capabilities of this information (ref. https://github.com/pkgjs/parseargs/issues/84)$ basic.js - --foo=bar -- --baz#!/usr/bin/env node
// basic.js
const { minargs } = require('minargs')
const { args, positionals, remainder, argv } = minargs()
args // { "foo": ["bar"] }
positionals // ["-"]
remainder // ["--baz"]
argv // [ { index: 0, type: 'argument', value: { name: "foo", value: "bar" } } ... ]$ exists.js --foo#!/usr/bin/env node
// exists.js
const { minargs } = require('minargs')
const { args } = minargs()
if (args.foo) {
// ...
}$ last-definition-.js --foo#!/usr/bin/env node
// exists.js
const { minargs } = require('minargs')
const { args } = minargs()
if (args.foo) {
// ...
}$ unknown.js --baz#!/usr/bin/env node
// unknown.js
const { minargs } = require('minargs')
const { args } = minargs()
const known = ['foo', 'bar']
const unknown = Object.keys(args).filter(arg => !known.includes(arg))
if (unknown.length > 0) {
console.error('unknown flags passed:', unknown)
// stop the process & set an `exitCode` appropriately
$ validate.js --num=1337#!/usr/bin/env node
// validate.js
const { minargs } = require('minargs')
const { args } = minargs()
const usage = {
num: {
validate: (value) => {
if (!isNaN(value)) {
return Number(value)
}
throw Error('Validation error!')
}
},
force: {
validate: (value) =>
$ recursive-parse.js#!/usr/bin/env node
// recursive-parse.js
const { minargs } = require('minargs')
console.log(minargs({ recursive: true }))
// ...$ mkdir.js ./path/to/new/dir/ --force --verbose --parents#!/usr/bin/env node
// mkdir.js
const known = ['force']
const { args, positionals } = minargs()
const cmd = (args.force) ? 'sudo mkdir' : 'mkdir'
const _args = Object.keys(flags).filter(f => known[f])
process('child_process').spawnSync(cmd, [..._args, ...positionals])$ usage.js -h#!/usr/bin/env node
// usage.js
const { minargs } = require('minargs')
const usage = {
help: {
short: 'h',
usage: 'cli --help',
description: 'Print usage information'
}
force: {
short: 'f',
usage: 'cli --force',
description: 'Run this cli tool with no restrictions'
}
}
const opts = {
alias: Object.keys(usage).
minargs does not assume anything about "known" or "unknown" arguments or their intended values (ex. defaults/types). Usage examples above show how you can quickly & easily utilize minargs as the backbone for an application which does enforce strictness/validation & more.-a) & combined (ex. -aCdeFg) shorts are supported-a=b will capture & return "b" as a value-a b will capture & return "b" as a value if positionalValues is truearg entry with a corresponding Array of String values.pop() on the Array (ex. args.foo.pop())alias?alias: { f: foo } will parse -f as { args: { "foo": [""] } })cmd --foo=bar baz the same as cmd baz --foo=bar?argv Array will change to reflect the differing positions of the arguments & positionals BUT args & positionals will remain consistent--no-foo coerce to --foo=false?--no-foo will parse to { args: { "no-foo": [""] } } & --foo-false to { args: { "no-foo": ["false"] } } respectively--foo the same as --foo=true?--foo will parse to { args: { "foo": [""] } } & --foo=true to { args: { "foo": ["true"] } } respectively-- signal the end of flags/options?-- definition will be returned in remainder.--?-- was present & there were arguments passed afterward is to check the value of remainder- a positional?- is treated as & returned in positionals-bar the same as --bar?-bar will be parsed as short options, expanding to -b, -a, -r (ref. Utility Syntax Guidelines in POSIX.1-2017)---foo the same as --foo?---foo returns { args: "-foo": [""] }--foo returns { args: { "foo": [""] }foo=bar a positional?minargs aligns with the POSIX Argument Syntax here (ie. "Arguments are options if they begin with a hyphen delimiter")--number -2 will be parsed as { args: { "number": [""], "2": [""] } }--number=-2) & may further require validation/type coercion to determine if the value is a Number (as is shown in the usage examples above)minargs has a companion CLI library: @minargs/cli
# install package globally & call bin...
npm install @minargs/cli -g && minargs
# or, use `npx` to install & call bin...
npx -- @minargs/cli "<args>" [<options>]minargs "<args>" [<options>]To learn more, check out the @minargs/cli GitHub repository or package page