ES6 generator-based CLI options parser.

ES6 generator-based CLI options parser.

Install | Synopsis | Usage | Example | Development | About


npm install parsec


Parsec is a hand-crafted CLI options parser using ES6 generators in ~150 LOC.

Parsec.parse(process.argv) // -T850 
  .options(["T", "terminator"], { default: 800 })
  .options("model", { default: 101 })
  .options("name", { default: "Schwa" })
  "T": "850",
  "terminator": "850",
  "model": "101",
  "m": "101",
  "name": "Schwa",
  "n": "Schwa"


Parsec automatically slices arguments starting from index 2, but you can specify the sliceIndex via the second argument to parse.

Parsec.parse(argv[, {
  sliceIndex = 2,
  operandsKey = "_",
  noFlags = true
  .options("option string")
  .options([aliases], { default })

Parsec uses the first letter of an option string as an alias:

Parsec.parse(["-tla"], { sliceIndex: 0 })
  "t": true,
  "l": true,
  "a": true,
  "three": true,
  "letter": true,
  "abbreviation": true

Pass an array of aliases, or specify default values via { default: value }

Parsec.parse(["-G"], { sliceIndex: 0 })
  .options(["G", "g", "great"])
  .options(["r", "R"], { default: 8 })

You can negate options using a --no- prefix before an option.

Parsec.parse(["--no-woman-no-cry", "--no-wonder=false"],
  { sliceIndex: 0 })
  "woman-no-cry": false,
  "wonder": true

The only one method you will probably deal with.

  • operandsKey = "_"
  • sliceIndex = 2
  • noFlags = true

Returns an iterator that yields objects of the form { prev, curr, next } for each item in a list.

Maps CLI arguments to custom Token objects.

  • Short Options
{ isShort, tokens }
  • Long Options
{ isLong, key, value, token }
  • Operands
{ token, isBare }

Token sub-iterator for short options.

Token iterator for options:

{ curr, next, value }

Iterator for entries:

{ key, value }

Use a different key name for the operands list.

Set to false to opt out.

Parsec.parse(["--no-love=false", "--no-war", "--no-no", "ok"],
  { sliceIndex: 0 })
    "love": true,
    "war": false,
    "no-no": "ok"


If your app receives the arguments ./app --foo bar -t now -xzy:


will return the following object:

  "foo": "bar",
  "t": "now",
  "x": true,
  "z": true,
  "y": true

This object also has an options method that you can use to customize the parsed options:

  .options("foo", { default: "hoge" })
  .options("time", { default: 24 })

returns the following object:

   "f": "bar",
   "foo": "bar",
   "t": "now",
   "time": "now",
   "x": true,
   "xoxo": true,
   "z": true,
   "zorg": true,
   "y": true,
   "yoyo": true

Note the first letter of the option string is used as the short option flag by default. You can opt out of this by specifying an array with the mappings you prefer:

.options(["foo", "F"])


Why another options CLI parser?. There are several options out there. There is yargs and commander (_> 1000 LOC_) which are fun to use, but end up doing too much.

There is also minimist and nopt, which are leaner and offer a more limited feature set, but I wasn't comfortable with their traditional design and large code base. I also found both slightly too verbose for my taste.

I decided to write my own solution (though it wasn't the first time) using ES6.

The end result is ~150 LOC and a readable code base.


git clone
cd parsec
npm install
npm run build

Roadmap ✈

  • Type support.
  • Invalid option checks.


MIT © Jorge Bucaran