Args

The @bomb.sh/args package is a <1kB library for parsing CLI flags. Inspired by Deno’s std/cli parseArgs module.

Features

🤏 very small

🍃 very simple

🏃 very fast (beats node:util)

🔏 strongly typed

Parsing the arguments

import { parse } from "@bomb.sh/args"

const args = parse(process.argv, {
  default: { a: 1, b: 2, c: "value" },
  alias: { h: "help" },
  boolean: ["foo", "bar"],
  string: ["baz", "qux"],
  array: ["input"],
});

• The first parameter is the raw CLI parameters list (in most case, it will be process.argv)
• The second parameter is the (optional) configuration to parse raw CLI parameters

Note

In this documentation, the term option indicate a string prefixed by one or two hyphen (-),
the term argument indicate a string that is not prefixed by hyphen:

• --long: is an option (long variant), named long
• -l: is an option (short variant), named l
• hello-world: is an argument, its value is hello-world

---

the term flag indicate an option that take two value: true or false

Parse options

default option

It provides the default value to set if the option is missing

import { parse } from "@bomb.sh/args"

const args = parse(process.argv, {
  default: { a: 1, b: 2, c: "value" },
});

the variable args will be equals to (assuming CLI parameters are my-command --a=27):

args = {
    _: [],
    a: 27,
    b: 2,
    c: 'value'
}

alias option

It offers an alternative name for an option.
The object key is the alternative name, the value the name used in the parsing result

import { parse } from "@bomb.sh/args"

const args = parse(process.argv, {
  alias: { h: 'help' },
});

the variable args will be equals to (assuming CLI parameters are my-command -h):

args = {
    _: [],
    help: true
}

boolean option

Indicate that an option is flag, and so argument after it is not its value

import { parse } from "@bomb.sh/args"

const args = parse(process.argv, {
  boolean: ['get'],
});

the variable args will be equals to (assuming CLI parameters are my-command --get http://my-url.com):

args = {
    _: ['http://my-url.com'],
    get: true
}

string option

Indicate that an option have a value, and so the argument after it is its value (or an empty string is none is available)

import { parse } from "@bomb.sh/args"

const args = parse(process.argv, {
  string: ['get', 'user'],
});

the variable args will be equals to (assuming CLI parameters are my-command --user --get http://my-url.com):

args = {
    _: [],
    user: '',
    get: 'http://my-url.com'
}

array option

Indicate that an option have a value and can be repeated several times

import { parse } from "@bomb.sh/args"

const args = parse(process.argv, {
  array: ['tag'],
});

the variable args will be equals to (assuming CLI parameters are my-command --tag app:v1 --tag app:latest):

args = {
    _: [],
    tag: ['app:v1', 'app:latest']
}

Special option

Negation variant

If a boolean option is prefixed by --no- it will parse as a false flag (without the no- prefix)

import { parse } from "@bomb.sh/args"

const args = parse(process.argv);

the variable args will be equals to (assuming CLI parameters are my-command --no-color):

args = {
    _: [],
    color: false
}

Note

If the option is defined as a string this behavior is ignored

import { parse } from "@bomb.sh/args"

const args = parse(process.argv, { string: ['no-name'] });

the variable args will be equals to (assuming CLI parameters are my-command --no-color --no-name John):

args = {
    _: [],
    'color': false
    'no-name': 'John'
}