mri

1.2.0 · active · verified Wed Apr 22

mri is a compact and high-performance library designed for quickly parsing command-line interface (CLI) flags and arguments in Node.js environments. It serves as a lightweight and significantly faster alternative to more feature-rich parsers like `minimist` and `yargs-parser`, often achieving 5x to 40x speed improvements respectively. The current stable version is 1.2.0. The project maintains an active release cadence, frequently publishing patch and minor versions that focus on performance optimizations, bug fixes, and minor feature additions. A key differentiator is its minimalist API, intentionally omitting complex features found in other parsers for raw speed, while still providing essential functionalities like aliasing, boolean and string type coercions, and default values. As of v1.2.0, TypeScript definitions are included directly within the package.

Common errors

```
Argument value for --flag is not a string/boolean, it's a number/different type or in the _ array.
```
cause The `options.default` setting uses its value's type to cast parsed arguments, or numerical values were auto-cast to numbers.

fix To force a specific type, add the flag to `options.boolean` or `options.string`. If `options.default` is causing issues, consider removing it or matching its type precisely to your expected input.
```
My `options.unknown` callback function is never being called when I pass unknown flags.
```
cause The `options.unknown` callback requires that `options.alias` also be populated, even if it's an empty object. Parsing also stops at the first unknown flag.

fix Ensure you provide an `options.alias` object (e.g., `{ alias: {} }`) in addition to `options.unknown`. Remember that parsing will stop immediately after the first unknown flag.
```
Short flags like '-abc' are not being parsed as individual boolean flags, or the value assigned to the last flag is incorrect.
```
cause `mri` treats short flag groups differently from some other parsers (like `minimist`), parsing them as individual booleans by default. If a value follows, it's assigned to the last flag in the group.

fix Adjust your expectation and logic to `mri`'s behavior: `-abc value` will result in `a:true, b:true, c:'value'`. If this is not desired, consider using long flags or separating short flags (e.g., `-a -b -c`).

Warnings

gotcha When `options.default` is used, the type of the default value will be used to cast the parsed argument. This can lead to unexpected type coercions or arguments being moved into the `_` (non-flag) array if they don't match the default's type.
Fix: Explicitly define types using `options.boolean` or `options.string` for critical flags, or ensure your code handles the potentially cast types. For example, `mri(['--foo', 'bar'], { default: { foo:true } })` will parse `foo` as `true` and `'bar'` into `_` because the default for `foo` is boolean.
gotcha Unlike `minimist`, `mri` treats short flag groups (e.g., `-abc`) as individual boolean flags by default. If a value follows, it will be assigned to the last flag in the group.
Fix: Adjust your CLI parsing logic to expect individual boolean flags for short groups. For example, `mri(['-abc', 'hello'])` will result in `{ _:[], a:true, b:true, c:'hello' }`, whereas `minimist` might interpret it differently.
gotcha The `options.unknown` callback will only be invoked if `options.alias` is also provided. Additionally, parsing terminates immediately upon encountering the first unknown flag, regardless of the callback's return value.
Fix: Ensure both `options.unknown` and `options.alias` are supplied if you intend to catch unknown flags. Design your CLI to handle this early termination behavior for unknown flags.
gotcha `mri` will attempt to cast numerical values directly to `Number` types where possible, unless a flag is explicitly listed in `options.boolean` or `options.string`.
Fix: If you need a numerical value to remain a string (e.g., '007'), you must explicitly include its key in `options.string`. Otherwise, be prepared to handle `Number` types for values that appear to be numerical.

Install

npm install mri npm
yarn add mri yarn
pnpm add mri pnpm

Imports

mri
```
import mri from 'mri';
```
The primary export is a default function. TypeScript types are bundled since v1.2.0, so no `@types/mri` is needed.
mri
wrong:
```
import mri from 'mri';
```
correct:
```
const mri = require('mri');
```
CommonJS `require` syntax for Node.js environments. Using `import` in a CJS module will lead to syntax errors or unexpected behavior.

Quickstart

Demonstrates basic parsing of CLI arguments, including boolean flags and aliases.

const mri = require('mri');

// Simulate process.argv for demonstration
const argv = ['--foo', '--bar=baz', '-mtv', '--', 'hello', 'world'];

console.log('Default parsing:');
console.log(mri(argv));
// Expected: { _: ['hello', 'world'], foo:true, bar:'baz', m:true, t:true, v:true }

console.log('\nParsing with boolean options:');
console.log(mri(argv, { boolean:['bar'] }));
// Expected: { _: ['baz', 'hello', 'world'], foo:true, bar:true, m:true, t:true, v:true }

console.log('\nParsing with aliases:');
console.log(mri(argv, {
  alias: {
    b: 'bar',
    foo: ['f', 'fuz']
  }
}));
// Expected: { _: ['hello', 'world'], foo:true, f:true, fuz:true, b:'baz', bar:'baz', m:true, t:true, v:true }

view raw JSON →