💛 You can help the author become a full-time open-source maintainer by sponsoring him on GitHub.

A tiny and flexible command-line argument parser for Node.js and Deno.

• Support combined short flags, -abc foo is expanded to -a -b -c foo
• Support using equal sign to specify argument value, -c=config.js is expanded to -c config.js
• Support positional arguments like your-cli foo bar
• Support collecting trailing arguments
• Support sub commands

npm i tinyargs

Deno users:

import { parse } from "https://deno.land/x/tinyargs/mod.ts"

import { parse } from "tinyargs"

const cli = parse(process.argv.slice(2), [
  { name: "help", flags: ["h"], type: Boolean, stop: true },
  { name: "version", flags: ["v"], type: Boolean, stop: true },
  { name: "files", type: String, positional: true, multiple: true },
])

if (cli.help) {
  console.log(`...your help message`)
  process.exit()
}

if (cli.version) {
  console.log(`...version number`)
  process.exit()
}

console.log(cli.files)

Run this cli:

$ node cli.js -h
...your help message

$ node cli.js -v
...version number

$ node cli.js foo.js bar.js
[ 'foo.js', 'bar.js' ]

$ node cli.js
error: missing positional argument: files

If -h, --help or -v, --version appears, the remaining arguments are not parsed, since we added stop: true to the option.

By default all options and positional arguments are required to have a value, if you add a string option named foo but it's used like --foo --bar, it will throw an error. This can be customized by setting optionalValue: true, which in this case would give foo a default value of true instead.

Create a CLI with two sub commands: (We use <> and [] to denote cli arguments in the docs, <> means it's required, [] means it's optional.)

• run <script> [args...]: like yarn run or npm run, run a script and collect trailing arguments so that you can pass them to the script later.
• download <url>: download from a url.

const cli = parse(process.argv.slice(2), [
  { name: "command", type: String, positional: true },
  {
    name: "script",
    type: String,
    positional: true,
    when: (cli) => cli.command === "run",
    stop: true,
  },
  {
    name: "url",
    type: String,
    positional: true,
    when: (cli) => cli.command === "download",
  },
])

if (cli.command === "run") {
  console.log(`...running ${cli.script} with forwarded arguments ${cli._}`)
} else if (cli.command === "download") {
  console.log(`...downloading ${cli.url}`)
} else {
  console.log(`...unknown command ${cli.command}`)
}

Define a flag that could be used as your-cli --file <value>, only name and type are required:

parse(process.argv.slice(2), [{ name: "file", type: String }])

Define a positional argument that could be used as your-cli <file>, by setting positional: true:

parse(process.argv.slice(2), [{ name: "file", type: String, positional: true }])

Flags can be repeated if you set multiple: true:

parse(process.argv.slice(2), [{ name: "file", type: String, multiple: true }])

Now your cli can be used as your-cli --file a.js --file b.js, the resulting object will look like: { file: [ 'a.js', 'b.js' ] }.

Positional arguments work in a similar fashion:

parse(process.argv.slice(2), [
  { name: "file", type: String, positional: true, multiple: true },
])

Now you can do your-cli a.js b.js, the resulting object will look like: { file: [ 'a.js', 'b.js' ] }.

Note that you can't have two multiple poitional arguments in the same command, because the first one will collect all positional arguments.

There're two way, first is to use the stop option, which will stop parsing arguments after the option, and arguments beyond that point will be collected under _ in the returned object:

const cli = parse(
  ["--foo", "bar", "baz", "--some-flag"],
  [{ name: "foo", type: Boolean, stop: true }],
)

console.log(cli)
// { foo: true, _: [ 'bar', 'baz', '--some-flag' ] }

The second way is to use positional: true with multiple: 'include-flags', which will collect trailing arguments into the specific option:

const cli = parse(
  ["--foo", "bar", "baz", "--some-flag"],
  [
    { name: "foo", type: Boolean },
    {
      name: "args",
      type: String,
      positional: true,
      multiple: "include-flags",
    },
  ],
)

console.log(cli)
// { foo: true, args: [ 'bar', 'baz', '--some-flag' ] }

https://www.jsdocs.io/package/tinyargs

MIT © EGOIST