zow

:computer: zod-inspired Typescript-first cli/args parser

Table of contents

• Introduction
• Behaviour and rules

Introduction

Parse your cli args and have proper typing and validation on the result.

Features

• Zero deps
• Simple
• Declarative API
• Support for single root command and tree of commands/trees
• (Incoming) Aliasing tree of commands to a specific command (the same way yarn runs yarn install).
• (Incoming) Autogenerated help and version commands

Example

import { command, flag, arg, opt } from 'zow'

command('run', {
// flags
  all: flag.boolean(),
  flat: flag.boolean(),
  threads: flag.number().default(4),
// args
  file: arg.string(0),
// opts
  remote: opt.string(0),
  location: opt.string(1).default('/tmp/asd')
}).root('my_command')
.onExec(v => {
  v /* => {
    all: true,
    flat: false,
    threads: 4,
    file: 'archive.zip',
    remote: undefined,
    location: '/tmp/asd',
  } */

  /* notice that typeof v = {
    all: boolean;
    flat: boolean;
    threads: number;
    regex: string | undefined;
    file: string;
    remote: string | undefined;
    location: string;
  } */
})
.processArgv('--all archive.zip qwe.zip')

If we were to call .processArgv() (as in, without arguments), process.argv will be used as default. If .root(...) was called on the tree/command then the first two "strings" of process.argv will be skipped.

What are inputs?

Inputs are the different values you could pass to a CLI.

In zow, we define three different types of inputs:

• flag
• arg
• opt

(You may find that these are called different in other CLI parsers)

Flag

A flag is an input that could have a value:

A very common example is the help as used here: some_command --help.

Some flags can also have values, for example: some_command --threads 4 probably means that the threads flag has a value of 4.

Notice how the help flag doesn't have a value. Whether a flag has a value or not is specified by the way a cli is configured.

This is important because if you run a command and set the value of flag that you think can have values but doesn't, then that value will use the value for something else and cause unexpected behaviour or confuse you.

What's an arg or an opt?

Arg

An arg is an input that is expected to be specified, so in the case of its abscence, the application should error.

For example, if we saw this in the help page: some_command <file>.

Then it means file is an arg of the command some_command.

Let's say we want to run that command with the file archive.zip,
we would run some_command archive.zip, and it would do with archive.zip whatever that command does with files.

Meanwhile, running some_command will fail because file was an arg (a required input), and we didn't specify a value for it.

Unlike flags, the value of an arg is not prefixed by its name.

For example: if you were to have more than one arg like some_command <input> <output>, then the position is how you would determine the value of each arg.

If we wanted input to be food and output to be poop,
then we would run some_command food poop.

But if we were to run some_command food it would fail because it has 2 args and we only passed 1.

Opt

Opt is similar to arg except they are not required, and they come after args (assuming there's any args).

You can pass none, any, or all of them, but in order, of course, as in, to pass a second opt you need to pass the first one.

In general, opts are enclosed with [] in help pages.

For example, in some_command input [<remote> <output>], input is an arg and remote and output are opts.

Generally, in CLIs that have opts, these have default values explained in their help pages.

Input positions

We refer to input positions to where a CLI parser allow flags to be specified in respect to args and opts.

Some CLI parsers are strict in that they expect flags to only come either before or after args or opts.

Other CLI parsers are lax in that they they could be before, after and even in between args and opts

Here in zow™ Inc. we are on the lax side.