# mri

> Quickly scan for CLI flags and arguments

Latest version **1.2.0** (published 2021-09-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install mri
pnpm add mri
yarn add mri
bun add mri
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2021-09-12 |
| First published | 2017-04-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=4 |
| Dependencies | 0 |
| Unpacked size | 13 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 681 |
| Author | Luke Edwards |
| Maintainers | lukeed |
| Keywords | argv, arguments, cli, minimist, options, optimist, parser, args |

## Links

- npm: https://www.npmjs.com/package/mri
- Repository: https://github.com/lukeed/mri
- Homepage: https://github.com/lukeed/mri#readme
- Issues: https://github.com/lukeed/mri/issues
- npm.io page: https://npm.io/package/mri

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 1.2.0 (latest) — 2021-09-12
- 1.1.6 — 2020-07-14
- 1.1.5 — 2020-03-24
- 1.1.4 — 2018-12-23
- 1.1.3 — 2018-12-21
- 1.1.2 — 2018-12-21
- 1.1.1 — 2018-05-07
- 1.1.0 — 2017-06-14
- 1.0.0 — 2017-06-12
- 0.1.0 — 2017-04-16

## README

# mri [![CI](https://github.com/lukeed/mri/workflows/CI/badge.svg?branch=master&event=push)](https://github.com/lukeed/mri/actions)

> Quickly scan for CLI flags and arguments

This is a [fast](#benchmarks) and lightweight alternative to [`minimist`](https://github.com/substack/minimist) and [`yargs-parser`](https://github.com/yargs/yargs-parser).

It only exists because I find that I usually don't need most of what `minimist` and `yargs-parser` have to offer. However, `mri` is similar _enough_ that it might function as a "drop-in replacement" for you, too!

See [Comparisons](#comparisons) for more info.

## Install

```sh
$ npm install --save mri
```

## Usage

```sh
$ demo-cli --foo --bar=baz -mtv -- hello world
```

```js
const mri = require('mri');

const argv = process.argv.slice(2);

mri(argv);
//=> { _: ['hello', 'world'], foo:true, bar:'baz', m:true, t:true, v:true }

mri(argv, { boolean:['bar'] });
//=> { _: ['baz', 'hello', 'world'], foo:true, bar:true, m:true, t:true, v:true }

mri(argv, {
  alias: {
    b: 'bar',
    foo: ['f', 'fuz']
  }
});
//=> { _: ['hello', 'world'], foo:true, f:true, fuz:true, b:'baz', bar:'baz', m:true, t:true, v:true }
```

## API

### mri(args, options)
Return: `Object`

#### args
Type: `Array`<br>
Default: `[]`

An array of arguments to parse. For CLI usage, send `process.argv.slice(2)`. See [`process.argv`](https://nodejs.org/docs/latest/api/process.html#process_process_argv) for info.

#### options.alias
Type: `Object`<br>
Default: `{}`

An object of keys whose values are `String`s or `Array<String>` of aliases. These will be added to the parsed output with matching values.

#### options.boolean
Type: `Array|String`<br>
Default: `[]`

A single key (or array of keys) that should be parsed as `Boolean`s.

#### options.default
Type: `Object`<br>
Default: `{}`

An `key:value` object of defaults. If a default is provided for a key, its type (`typeof`) will be used to cast parsed arguments.

```js
mri(['--foo', 'bar']);
//=> { _:[], foo:'bar' }

mri(['--foo', 'bar'], {
  default: { foo:true, baz:'hello', bat:42 }
});
//=> { _:['bar'], foo:true, baz:'hello', bat:42 }
```

> **Note:** Because `--foo` has a default of `true`, its output is cast to a Boolean. This means that `foo=true`, making `'bar'` an extra argument (`_` key).

#### options.string
Type: `Array|String`<br>
Default: `[]`

A single key (or array of keys) that should be parsed as `String`s.

#### options.unknown
Type: `Function`<br>
Default: `undefined`

Callback that is run when a parsed flag has not been defined as a known key or alias. Its only parameter is the unknown flag itself; eg `--foobar` or `-f`.

Once an unknown flag is encountered, parsing will terminate, regardless of your return value.

> **Note:** `mri` _only_ checks for unknown flags if `options.unknown` **and** `options.alias` are populated. Otherwise, everything will be accepted.


## Comparisons

#### minimist

- `mri` is 5x faster (see [benchmarks](#benchmarks))
- Numerical values are cast as `Number`s when possible
  - A key (and its aliases) will always honor `opts.boolean` or `opts.string`
- Short flag groups are treated as `Boolean`s by default:
    ```js
    minimist(['-abc', 'hello']);
    //=> { _:[], a:'', b:'', c:'hello' }

    mri(['-abc', 'hello']);
    //=> { _:[], a:true, b:true, c:'hello' }
    ```
- The `opts.unknown` behaves differently:
  - Unlike `minimist`, `mri` will not continue continue parsing after encountering an unknown flag
- Missing `options`:
  - `opts.stopEarly`
  - `opts['--']`
- Ignores newlines (`\n`) within args (see [test](https://github.com/substack/minimist/blob/master/test/parse.js#L69-L80))
- Ignores slashBreaks within args (see [test](https://github.com/substack/minimist/blob/master/test/parse.js#L147-L157))
- Ignores dot-nested flags (see [test](https://github.com/substack/minimist/blob/master/test/parse.js#L180-L197))

#### yargs-parser

- `mri` is 40x faster (see [benchmarks](#benchmarks))
- Numerical values are cast as `Number`s when possible
  - A key (and its aliases) will always honor `opts.boolean` or `opts.string`
- Missing `options`:
  - `opts.array`
  - `opts.config`
  - `opts.coerce`
  - `opts.count`
  - `opts.envPrefix`
  - `opts.narg`
  - `opts.normalize`
  - `opts.configuration`
  - `opts.number`
  - `opts['--']`
- Missing [`parser.detailed()`](https://github.com/yargs/yargs-parser#requireyargs-parserdetailedargs-opts) method
- No [additional configuration](https://github.com/yargs/yargs-parser#configuration) object
- Added [`options.unknown`](#optionsunknown) feature


## Benchmarks

> Running Node.js v10.13.0

```
Load Times:
  nopt          3.179ms
  yargs-parser  2.137ms
  minimist      0.746ms
  mri           0.517ms

Benchmark:
  minimist      x    328,747 ops/sec ±1.09% (89 runs sampled)
  mri           x  1,622,801 ops/sec ±0.94% (92 runs sampled)
  nopt          x    888,223 ops/sec ±0.22% (92 runs sampled)
  yargs-parser  x     30,538 ops/sec ±0.81% (91 runs sampled)
```

## License

MIT © [Luke Edwards](https://lukeed.com)

---
_Source: https://npm.io/package/mri · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._