• Public
  • Public/Protected
  • All



npm versionnpm downloads Twitter Follow

This project is part of the @thi.ng/umbrella monorepo.


Declarative, functional & typechecked CLI argument/options parser, value coercions etc..

Includes built-in support for the following argument types (of course custom arg types are supported too):

Argument typeMultipleExampleResult
Flag--force, -fforce: true
String--foo barfoo: "bar"
Float/int/hex--bg ff997fbg: 16750975
Enum--type pngtype: "png"
KV pairs--define foo=bardefine: { foo: "bar" }
KV multi pairs-D foo=bar -D foo=bazdefine: { foo: ["bar", "baz"] }
JSON--config '{"foo": [23]}'config: { foo: [23] }
Fixed size tuple--size 640x480size: { value: [640, 480] }

If multiple values/repetitions are allowed for an argument, the values will be collected into an array (apart from KV pairs, which will yield an object). Furthermore, for multi-args, an optional delimiter can be specified to extract individual values, e.g. -a 1,2,3 equals -a 1 -a 2 -a 3


STABLE - used in production

Search or submit any issues for this package


yarn add @thi.ng/args

ES module import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/args"></script>

Skypack documentation

For NodeJS (v14.6+):

node --experimental-specifier-resolution=node --experimental-repl-await

> const args = await import("@thi.ng/args");

Package sizes (gzipped, pre-treeshake): ESM: 2.45 KB



Generated API docs

Basic usage

type ImgType = "png" | "jpg" | "gif" | "tiff";

// CLI args will be validated against this interface
interface TestArgs {
configPath?: string;
force: boolean;
bg: number;
type: ImgType;
size?: Tuple<number>;
pos?: Tuple<number>;
xtra?: { a: number; b: string };
define?: KVDict;

// arg specifications
const specs: Args<TestArgs> = {
// string arg
configPath: string({
alias: "c",
hint: "PATH",
desc: "Config file path (CLI args always take precedence over those settings)",
// boolean flag (default: false)
force: flag({
alias: "f",
desc: "Force operation",
// side effect & predicate
// parsing only continues if fn returns true
fn: (_) => (console.log("force mode enabled"), true),
// hex int value
bg: hex({
desc: "Background color",
// mandatory args require a `default` value and/or `optional: false`
default: 0xffffff,
// enum value (mandatory)
type: oneOf(["png", "jpg", "gif", "tiff"], {
alias: "t",
desc: "Image type",
// mandatory args require a `default` value and/or `optional: false`
optional: false,
// fixed size numeric tuple w/ `x` as delimiter
// size: tuple(coerceInt, 2, { hint: "WxH", desc: "Target size" }, "x"),
// syntax sugar for above:
size: size(2, { hint: "WxH", desc: "Target size" }),
// another version for tuples of floating point values
// pos: tuple(coerceFloat, 2, { desc: "Lat/Lon" }, ","),
pos: vec(2, { desc: "Lat/Lon" }),
// JSON string arg
xtra: json({
alias: "x",
desc: "Extra options",
// key-value pairs parsed into an object
define: kvPairs({ alias: "D", desc: "Define dict entry" }),

try {
// parse argv w/ above argument specs & default options
// (by default usage is shown if error occurs)
const args = parse(specs, process.argv);
} catch (_) {}

Generate & display help

Usage information can be generated via usage() and is automatically triggered via the special --help option (configurable, see ParseOpts).

Each arg can be associated with arbitrary group IDs, which are then used to segment usage output. By default, flag() args are assigned to a "flags" group, all others to "main". The default output order too is ["flags", "main"], but can be configured via a group option given an arg spec or factory function.

By default, ANSI colors are used to format the result string of usage(), but can be disabled (see UsageOpts).

ts-node index.ts --help

-f, --force                     Force operation

--bg HEX                        Background color
-c PATH, --config-path PATH     Config file path (CLI args always take
                                precedence over those settings)
-D key=val, --define key=val    [multiple] Define dict entry
--pos N,N                       Lat/Lon
--size WxH                      Target size
-t ID, --type ID                [required] Image type: 'png', 'jpg', 'gif',
-x JSON, --xtra JSON            Extra options

Parsing, value coercions & side effects

The below invocation demonstrates how the various argument types are handled & represented in the result. Parsing stops with the first non-argument value (here sourcefile.png) and the remaining values are made available via rest in the result object.

ts-node index.ts \
-f -t png --bg ff00ff --size 640x480 \
-D author=toxi -D date=2018-03-24 \
--xtra '{"foo": [23]}' \

# force mode enabled
# {
# result: {
# force: true,
# type: 'png',
# bg: 16711935,
# size: Tuple { value: [640, 480] }
# define: { author: 'toxi', date: '2018-03-24' },
# xtra: { foo: [23] },
# },
# index: 15,
# rest: [ 'sourcefile.png' ],
# done: false
# }


Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

  title = "@thi.ng/args",
  author = "Karsten Schmidt",
  note = "https://thi.ng/args",
  year = 2018


© 2018 - 2021 Karsten Schmidt // Apache Software License 2.0

Generated using TypeDoc