@reliverse/reliarg

📦 NPM • ✨ Repo • 💬 Discord

A zero-dependency CLI argument parser built for clarity, predictability, and modern TypeScript devs.
@reliverse/reliarg handles booleans, aliases, default values, strict/loose modes, arrays, negated flags, and more — without the weird edge cases.

Why Reliarg?

• ✌️ Drop-in alternative to mri, minimist, and others
• 🧠 Feature-rich: aliases, defaults, strict mode, booleans, negated flags, arrays, etc.
• 🚫 No weird coercion or hidden type conversions
• 📦 Zero dependencies and minimal footprint
• 🔍 Predictable parsing — with opt-in warnings for unknown flags
• 💥 Strict mode that throws on mistakes
• 🔬 Thoroughly manually tested for edge cases: --no-foo, -abc, --flag=value, and more
• 🧪 Production-ready since all ./tests/args-impl.test.ts tests passed via bun test

Install

bun add @reliverse/reliarg
# bun • pnpm • yarn • npm

Quickstart

import { reliArgParser } from "@reliverse/reliarg";

const argv = process.argv.slice(2); // e.g. ["--name=Reliverse", "-v", "file.txt"]
const result = reliArgParser(argv, {
  boolean: ["verbose"],
  alias: { v: "verbose" },
});

console.log(result);
/*
  {
    name: "Reliverse",
    verbose: true,
    _: ["file.txt"]
  }
*/

In this quick example:

• --name=Reliverse => name: "Reliverse"
• -v => alias for --verbose, so verbose: true
• file.txt => goes into _ array

See Detailed Examples below for more advanced usage.

Features You’ll Use

Feature	Description
Aliases	Map multiple short flags to long flags. E.g. v -> verbose
Defaults	Pre-fill missing flag values. E.g. { cache: true }
Boolean	Force flags to parse as booleans, auto-casting "true"/"false"
Negated flags	--no-cache => { cache: false } (only if cache is in boolean)
Array	Repeated flags accumulate into an array, e.g. --include file1 file2
Strict mode	Throw on unknown flags – no surprises
warnOnUnknown	Logs a warning for unknown flags if not strict
-- support	Everything after -- is treated as positional (no more flag parsing)
Unknown flag hook	A custom function unknown(flag => boolean) to allow certain unknown flags

Detailed Examples

1. Using Booleans and Defaults

import { reliArgParser } from "@reliverse/reliarg";

const argv = ["--no-cache", "--debug"];
const parsed = reliArgParser(argv, {
  boolean: ["cache", "debug"],
  defaults: { cache: true },
});

console.log(parsed);
// {
//   cache: false, // because of --no-cache
//   debug: true,  // because "debug" is boolean and present
//   _: []
// }

2. Short Flags Grouping

mycli -abc=123

If we declare boolean: ["a", "b"], then:

{
  a: true,
  b: true,
  c: "123",
  _: []
}

3. Arrays

const argv = [
  "--include=src", 
  "--include=tests",
  "--include", "build",
  "script.js"
];

const parsed = reliArgParser(argv, {
  array: ["include"],
});

Now the result accumulates repeats:

{
  include: ["src", "tests", "build"],
  _: ["script.js"]
}

4. Stop Early

mycli build docs -v

If stopEarly is true, we stop parsing at first positional build:

reliArgParser(["build", "docs", "-v"], {
  stopEarly: true,
});
// => { _: ["build", "docs", "-v"] }

5. Unknown Flag Hook

reliArgParser(["--foo", "--custom-bar"], {
  unknown: (flag) => flag.startsWith("custom-"), 
});
// => { "custom-bar": true, _: ["--foo"] }

Configuration Options

All options are optional. Here’s a brief overview:

• boolean?: string[]
  Flags that parse as booleans (true/false).
• defaults?: Record<string, unknown>
  Key-value defaults, e.g. defaults: { cache: true }.
• alias?: Record<string, string | string[]>
  Map from short to long flags, or multiple aliases for a single key.
• strict?: boolean
  Throw on unknown flags.
• warnOnUnknown?: boolean
  Print console warnings for unknown flags.
• negatedBoolean?: boolean (default: true)
  Support --no-foo => foo: false.
• parseNumbers?: boolean (default: false)
  Convert numeric strings to numbers for non-boolean flags.
• allowNegativeNumbers?: boolean (default: true)
  If false, -123 is parsed as a short flag instead of a positional.
• stopEarly?: boolean
  Once a positional argument is encountered, push everything else into _.
• array?: string[]
  Flags that should accumulate repeated values into an array.
• string?: string[]
  Flags that should always remain strings (even with parseNumbers = true).
• unknown?: (flagName: string) => boolean
  Callback to allow or block unknown flags.

Strict & Unknown Flag Handling

1. Strict Mode

   reliArgParser(["--foo"], { strict: true });
   // ❌ Throws: Error: Unknown flag: --foo

2. warnOnUnknown

   reliArgParser(["--foo"], { warnOnUnknown: true });
   // Logs: "Unknown flag: --foo"
   // => { _: [] }

3. unknown function

   reliArgParser(["--foo"], {
     unknown: (f) => f.startsWith("foo"), // allow flags that start with "foo"
   });
   // => { foo: true }

Development & Testing

git clone https://github.com/reliverse/reliarg
cd reliarg
bun i
bun dev

• 🔜 Examples: Check out /examples for quick demos.
• Tests: Run bun test to see the extensive test suite that covers edge cases like negated booleans, short flags with attached values, arrays, etc.

Related & Shoutouts

• @reliverse/rempts – Batteries-included CLI engine
• @reliverse/reglob – Tiny fast globbing
• @reliverse/cli – All-in-one CLI for building and improving web projects

Shoutouts

• mri
• nopt
• minimist
• yargs-parser

License

MIT © blefnk Nazar Kornienko & Reliverse

If this saved you time or headaches, please consider starring the repo or sponsoring @blefnk. I love seeing my tools help the community!