tinyargs
Version:
A tiny and flexible command-line argument parser for Node.js and Deno.
196 lines (138 loc) • 5.37 kB
Markdown
**💛 You can help the author become a full-time open-source maintainer by [sponsoring him on GitHub](https://github.com/sponsors/egoist).**
---
# tinyargs
[](https://npm.im/tinyargs) [](https://npm.im/tinyargs) [](https://coveralls.io/github/egoist/tinyargs?branch=main)
A tiny and flexible command-line argument parser for Node.js and Deno.
## Features
- 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
## Install
```bash
npm i tinyargs
```
[Deno](https://deno.land) users:
```ts
import { parse } from "https://deno.land/x/tinyargs/mod.ts"
```
## Examples
### Simple Example
```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:
```bash
$ 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.
### Sub Commands
Create a CLI with two sub commands: (<small>_We use `<>` and `[]` to denote cli arguments in the docs, `<>` means it's required, `[]` means it's optional._</small>)
- `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.
```ts
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}`)
}
```
## Guide
### Flags
Define a flag that could be used as `your-cli --file <value>`, only `name` and `type` are required:
```ts
parse(process.argv.slice(2), [{ name: "file", type: String }])
```
### Positional Arguments
Define a positional argument that could be used as `your-cli <file>`, by setting `positional: true`:
```ts
parse(process.argv.slice(2), [{ name: "file", type: String, positional: true }])
```
### Repeated / Multiple Flags and Positional Arguments
Flags can be repeated if you set `multiple: true`:
```ts
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:
```ts
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.
### Collecting Trailing 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:
```ts
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:
```ts
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' ] }
```
## API Reference
https://www.jsdocs.io/package/tinyargs
## Sponsors
[](https://github.com/sponsors/egoist)
## License
MIT © [EGOIST](https://github.com/sponsors/egoist)