A thin and strongly typed CLI arguments parser for Node.js.
Usage
Install
# pnpmpnpm add argue-cli# yarnyarn add argue-cli# npmnpm i argue-cli
Import in your code and use it!
import { read, end, expect, alias, option, readOptions } from 'argue-cli'/** * Expect and read one of the commands */const command = expect( alias('install', 'i'), 'remove')let options = {}if (command === 'install') { /** * Read passed options */ options = readOptions( option(alias('save', 'S'), Boolean), option(alias('saveDev', 'save-dev',
API
Argue reads arguments sequentially from an internal state, which is initialized with process.argv. Every call consumes the arguments it reads, so you describe your CLI step by step: expect a command, read its options, read positional arguments, and finally assert the end.
[!TIP]
The internal state can be controlled manually with setArgs(...args) and resetArgs() — handy in tests.
read
function read(): string
Reads the next argument and returns it. Throws an error if there are no arguments left.
Expects the next argument to be one of the given ones and returns the matched name. If an alias matches, the main name is returned. Throws an error on any other input.
The return type is inferred as a union of the given names:
Describes an argument that matches both camelCase and kebab-case forms. The name can be given in either form — the twin form is added as an alias. Aliases longer than one character are autocased too. Use it anywhere an argument name is expected.
autocase('firstRelease')// --firstRelease and --first-release are both acceptedautocase(alias('save-dev', 'D'))// --save-dev, --saveDev and -D
option
function option(argRef: ArgRef, type: OptionConstructor): OptionReader
Describes an option with a value of the given type, to be read by readOptions:
String — takes the next argument as a value: --workspace packages/app
Number — parses the next argument as a number: --port 8080
Boolean — a flag without a value, true when present: --verbose
Array — splits the next argument by commas; repeated options are merged: --plugins eslint,swc --plugins tsc → ['eslint', 'swc', 'tsc']
[String] or [Number] — takes the next argument as a whole; repeated options are collected: --match '*.{js,ts}' --match '*.css' → ['*.{js,ts}', '*.css']. Use it instead of Array for values that may contain commas of their own
flag
function flag(argRef: ArgRef): OptionReader
Describes a boolean flag with --no-* negation support, to be read by readOptions: --verbose sets true, --no-verbose sets false. Use option(argRef, Boolean) when negation is not wanted.
function readOptions(...optionReaders: OptionReader[]): OptionResult
Scans the arguments and reads all described options. Both --option and -o prefixes are accepted, and a value can be passed either as the next argument or inline: --workspace packages/app and --workspace=packages/app are equivalent. Arguments that don't match any described option are left untouched, so you can continue reading them afterwards.
The result is a strongly typed object, where every property is optional — an option simply may not be passed: