Type-Safe CLI Argument Parser

1.0.3 · active · verified Wed Apr 22

cli-vir is a command-line interface (CLI) argument parser for Node.js, built with a strong emphasis on type safety for parsed arguments. The current stable version is 1.0.3, indicating active development with frequent patch releases addressing minor issues and dependency updates. Key differentiators include its flexible handling of flag formats (single/double dashes, short/long forms), support for case-insensitive flag names across camelCase, kebab-case, and snake_case variants, and robust options to restrict argument values to specific sets or convert truthy/falsy strings to booleans. It provides comprehensive type inference for parsed values and automatically generates man-page-style documentation for parsing failures. This library streamlines CLI development by abstracting away common parsing complexities and enhancing developer experience with strong type guarantees. It requires Node.js version 22 or higher.

Common errors

```
TypeError: parseArgs is not a function
```
cause Attempting to use `require()` syntax for `cli-vir`, which is an ESM-first module.

fix Change your import statement to use ESM syntax: `import { parseArgs } from 'cli-vir';` and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
```
TS2345: Argument of type 'string' is not assignable to parameter of type 'boolean'.
```
cause A flag argument was defined without a `valueRequirement` or with `FlagRequirement.Blocked`, implying a boolean flag, but a string value was provided on the command line.

fix Adjust your `FlagRequirement` in the argument definition (e.g., `FlagRequirement.Required` for a string value) or ensure the CLI input matches the expected type (e.g., pass the flag without a value for a boolean flag).
```
ReferenceError: import_meta is not defined
```
cause The `import.meta` object is used in the `parseArgs` options but the file is being executed in a CommonJS context or an environment where `import.meta` is not available.

fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and you are running Node.js version 12.0.0 or higher, where `import.meta` was introduced for ESM modules.

Warnings

breaking The `ParsedArg` type was renamed to `ParsedArgs`. If you were explicitly typing your parsed arguments, you must update the type name.
Fix: Update `ParsedArg` to `ParsedArgs` in your type annotations: `import type { ParsedArgs } from 'cli-vir';`
breaking Version 1.0.0 introduced a major bump, which may include breaking changes in internal structures or API behavior not explicitly detailed in release notes beyond 'bump to v1'. It also added support for an array of binary names. Review the GitHub comparison for specific changes if migrating from pre-1.0.0 versions.
Fix: Consult the commit history (v0.2.0...v1.0.0) for detailed changes and adjust your code accordingly. Pay attention to how `binName` is configured if you use multiple entry points.
gotcha cli-vir requires Node.js version 22 or higher. Running it on older Node.js versions will result in runtime errors due to unsupported syntax or APIs.
Fix: Ensure your project's Node.js environment is updated to version 22 or later. You can use a tool like `nvm` to manage Node.js versions.
gotcha For correct `binName` detection and automatic exclusion from `process.argv`, you must pass `import.meta` from your top-level executed JavaScript/TypeScript file to the `parseArgs` options. Incorrect usage may lead to `binName` not being resolved correctly or arguments being misinterpreted.
Fix: Always provide `{ importMeta: import.meta }` in the options object when calling `parseArgs` from your main CLI entry point.

Install

npm install cli-vir npm
yarn add cli-vir yarn
pnpm add cli-vir pnpm

Imports

parseArgs
wrong:
```
const parseArgs = require('cli-vir').parseArgs;
```
correct:
```
import { parseArgs } from 'cli-vir';
```
cli-vir is primarily an ESM module, requiring 'import' syntax. Node.js >=22 is a prerequisite.
FlagRequirement
wrong:
```
import FlagRequirement from 'cli-vir';
```
correct:
```
import { FlagRequirement } from 'cli-vir';
```
FlagRequirement is a named export, not a default export.
ParsedArgs
wrong:
```
import { ParsedArg } from 'cli-vir';
```
correct:
```
import type { ParsedArgs } from 'cli-vir';
```
The type was renamed from `ParsedArg` to `ParsedArgs` in v0.1.1. Always use `import type` for type-only imports.

Quickstart

This example demonstrates how to parse command-line arguments with type safety, defining flags and positional arguments, and handling multiple values for a flag. It shows the basic setup with `parseArgs` and how to access the typed results.

import { FlagRequirement, parseArgs } from 'cli-vir';

// Simulate command-line arguments for demonstration
// Example: node my-cli.js --arg1 --arg3 valueA --arg3 valueB arg2Value
const simulatedArgs = ['node', 'my-cli.js', '--arg1', '--arg3', 'valueA', '--arg3', 'valueB', 'arg2Value'];

const myArgs = parseArgs(
    simulatedArgs, // In a real CLI, use process.argv
    {
        arg1: {
            flag: {
                valueRequirement: FlagRequirement.Blocked,
                description: 'A simple boolean flag.'
            }
        },
        arg2: {
            required: true,
            position: 0,
            description: 'A required positional argument.'
        },
        arg3: {
            flag: {
                aliases: ['-3'],
                allowMultiple: true,
                valueRequirement: FlagRequirement.Required,
                description: 'A flag that can be provided multiple times.'
            }
        },
        rest: {
            position: 'rest',
            description: 'Any remaining positional arguments.'
        }
    },
    {
        binName: 'my-cli.js', // Or the actual binary name if using a 'bin' entry in package.json
        importMeta: import.meta,
    },
);

console.log('Parsed Arguments:');
console.log(`arg1: ${myArgs.arg1} (type: ${typeof myArgs.arg1})`); // boolean
console.log(`arg2: ${myArgs.arg2} (type: ${typeof myArgs.arg2})`); // string
console.log(`arg3: ${JSON.stringify(myArgs.arg3)} (type: ${typeof myArgs.arg3})`); // string[]
console.log(`rest: ${JSON.stringify(myArgs.rest)}`); // string[]

// Example: Accessing a non-existent arg will result in a TypeScript error and runtime undefined
// console.log(myArgs.nonExistentArg); // TS Error: Property 'nonExistentArg' does not exist on type '{ arg1: boolean; arg2: string; arg3: string[]; rest: string[]; }'.

view raw JSON →