minargs

minargs is meant to be a primitive library which expands the current process.argv information for developers that want to quickly write CLI tools with minimal configuration, assumptions & dependencies. Argument parsing can take many shapes but the explicit goals of this library are as follows:

Goals

• no usage
• no validation
• no types or type cohersion
• no regular expressions
• no strictness
• no dependencies
• minimal assumptions
• minimal configuration
• minimal information loss

Package

Installation

npm install minargs

Usage

// program.js - --foo=bar
const { minargs } = require('minargs')
const { args, values, positionals } = minargs()

args.foo // true
values.foo // 'bar'
positionals // ['-']

Options

• known (Array) Default: none
• multiples (Array) Default: none
• positionalValues (Array) Default: none

Response Object

{
  args: {},
  values: {},
  positionals: [],
  remainder: [],
  process: []
}

args

values

• Returned values are a string by default
• Returned values are an array of strings if the corresponding arg was defined in multiples
• Examples:
  • --foo=bar will return undefined with no configuration
  • --foo=bar will return "bar" when 'foo'
  • --foo bar will return "bar" when 'foo' & positionalValues is true
    • Notably, bar is treated as a positional & returned in positionals if positionalValues is false

positionals

remainder

process

CLI

minargs comes with a CLI out-of-the-box to make it a little easier to try/use the parser & test any assumptions about input.

Installation

# install package globally & call bin...
npm install minargs -g && minargs

# or, use `npx` to install & call bin...
npx minargs

Usage

minargs "<args>" [<options>]

Options

• --known (alias: k)
• --multiple (alias: m)
• --alias (alias: a)
• --positionalValues (alias: p) Default: false
• --strict (alias: s) Default: false

Examples

Get the # of times a arg was defined (using multiples & alias')...

minargs "--foo -f -f -ffff" -m foo -a f:foo | jq.values.length

Piping to/reading from stdin...

"--foo --bar baz" | minargs -k bar -v bar -s

Extended Use Cases

Handling usage

Handling validation

Handling recursive parsing

F.A.Q.

Are shorts supported?

• Yes.
• -a & -aCdeFg are supported
• -a=b will capture & return "b" as a value
• -a b will capture & return "b" as a value if positionalValues is true

What is an alias?

• An alias can be any other string that maps to the canonical option; this includes single characters which will map shorts to a long-form (ex. alias: { f: foo } will parse -f as { args: { 'foo': true } })

Is cmd --foo=bar baz the same as cmd baz --foo=bar?

• Yes.

Is value validation or type cohersion supported?

• No.

Are usage errors supported?

• No.

Does --no-foo coerce to --foo=false?

• No.
• It would set { args: { 'no-foo': true } }

Is --foo the same as --foo=true?

• No.

Are environment variables supported?

• No.

Do unknown arguments raise an error?

• When strict=false, no.
• When strict=true, yes.

Does -- signal the end of flags/options?

• Yes.
• Any arguments following a bare -- definition will be returned in remainder.

Is a value stored to represent the existence of --?

• No.
• The only way to determine if -- was present & there were arguments passed afterward is to check the value of remainder

Is - a positional?

• Yes.
• A bare - is treated as & returned in positionals

Is -bar the same as --bar?

• No.
• -bar will be parsed as short options, expanding to -b, -a, -r (ref. Utility Syntax Guidelines in POSIX.1-2017)

Is ---foo the same as --foo?

• No.
• ---foo returns { args: '-foo': true }
• --foo returns { args: { 'foo': true }

Is foo=bar a positional?

• Yes.