Skip to content

Args

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

🤏 very small

🍃 very simple

🏃 very fast (beats node:util)

🔏 strongly typed

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

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'
}

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
}

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
}

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'
}

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']
}

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
}