argv-flags

Schema-based CLI flag parsing with deterministic, machine-readable results.

What it is

argv-flags parses command-line tokens against an explicit schema and returns typed values plus stable issue codes.

Install

npm install argv-flags
deno add jsr:@ismail-elkorchi/argv-flags

Quickstart

import { defineSchema, parseArgs } from "argv-flags";

const schema = defineSchema({
  src: { type: "string", flags: ["--src"], required: true },
  dest: { type: "string", flags: ["--dest"], required: true },
  verbose: { type: "boolean", flags: ["--verbose"], default: false },
});

const result = parseArgs(schema, { argv: ["--src", "a.txt", "--dest", "b.txt"] });

if (!result.ok) {
  console.error(result.issues);
  process.exitCode = 1;
}

console.log(result.values.src, result.values.dest);

Options reference

• Options reference
• 10-minute tutorial: first CLI

When not to use

• You only need ad-hoc parsing for a one-off script.
• You need subcommand routing or interactive prompts.
• You target CommonJS or Node < 24.

When to use

• You need deterministic parsing with stable issue codes.
• You want the same schema on Node, Deno, and Bun.
• You need machine-readable results for automation.

Compatibility

• Module system: ESM-only.
• Runtimes: Node >=24, current Deno, current Bun.
• JSON schema workflows use readFileSync(...); JSON.parse(...) (no JSON import attributes required).

Links

• Docs index
• Reference:
  • Reference index
  • Parse-result JSON schema
  • Security policy
• How-to:
  • First CLI tutorial
  • How-to index
  • Contributing
• Explanation: explanation index

Verification

npm run examples:run
npm run check:fast
npm run check

License

MIT