{"id":17039,"library":"mri","title":"mri","description":"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.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/lukeed/mri","tags":["javascript","argv","arguments","cli","minimist","options","optimist","parser","args","typescript"],"install":[{"cmd":"npm install mri","lang":"bash","label":"npm"},{"cmd":"yarn add mri","lang":"bash","label":"yarn"},{"cmd":"pnpm add mri","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary export is a default function. TypeScript types are bundled since v1.2.0, so no `@types/mri` is needed.","symbol":"mri","correct":"import mri from 'mri';"},{"note":"CommonJS `require` syntax for Node.js environments. Using `import` in a CJS module will lead to syntax errors or unexpected behavior.","wrong":"import mri from 'mri';","symbol":"mri","correct":"const mri = require('mri');"}],"quickstart":{"code":"const mri = require('mri');\n\n// Simulate process.argv for demonstration\nconst argv = ['--foo', '--bar=baz', '-mtv', '--', 'hello', 'world'];\n\nconsole.log('Default parsing:');\nconsole.log(mri(argv));\n// Expected: { _: ['hello', 'world'], foo:true, bar:'baz', m:true, t:true, v:true }\n\nconsole.log('\\nParsing with boolean options:');\nconsole.log(mri(argv, { boolean:['bar'] }));\n// Expected: { _: ['baz', 'hello', 'world'], foo:true, bar:true, m:true, t:true, v:true }\n\nconsole.log('\\nParsing with aliases:');\nconsole.log(mri(argv, {\n  alias: {\n    b: 'bar',\n    foo: ['f', 'fuz']\n  }\n}));\n// Expected: { _: ['hello', 'world'], foo:true, f:true, fuz:true, b:'baz', bar:'baz', m:true, t:true, v:true }","lang":"javascript","description":"Demonstrates basic parsing of CLI arguments, including boolean flags and aliases."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.1.0"},{"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.","message":"`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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The `options.default` setting uses its value's type to cast parsed arguments, or numerical values were auto-cast to numbers.","error":"Argument value for --flag is not a string/boolean, it's a number/different type or in the _ array."},{"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.","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.","error":"My `options.unknown` callback function is never being called when I pass unknown flags."},{"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`).","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.","error":"Short flags like '-abc' are not being parsed as individual boolean flags, or the value assigned to the last flag is incorrect."}],"ecosystem":"npm","meta_description":null}