{"id":16970,"library":"cli-vir","title":"Type-Safe CLI Argument Parser","description":"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.","status":"active","version":"1.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/electrovir/cli-vir","tags":["javascript","cli","args","parser","type-safe","typescript"],"install":[{"cmd":"npm install cli-vir","lang":"bash","label":"npm"},{"cmd":"yarn add cli-vir","lang":"bash","label":"yarn"},{"cmd":"pnpm add cli-vir","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"cli-vir is primarily an ESM module, requiring 'import' syntax. Node.js >=22 is a prerequisite.","wrong":"const parseArgs = require('cli-vir').parseArgs;","symbol":"parseArgs","correct":"import { parseArgs } from 'cli-vir';"},{"note":"FlagRequirement is a named export, not a default export.","wrong":"import FlagRequirement from 'cli-vir';","symbol":"FlagRequirement","correct":"import { FlagRequirement } from 'cli-vir';"},{"note":"The type was renamed from `ParsedArg` to `ParsedArgs` in v0.1.1. Always use `import type` for type-only imports.","wrong":"import { ParsedArg } from 'cli-vir';","symbol":"ParsedArgs","correct":"import type { ParsedArgs } from 'cli-vir';"}],"quickstart":{"code":"import { FlagRequirement, parseArgs } from 'cli-vir';\n\n// Simulate command-line arguments for demonstration\n// Example: node my-cli.js --arg1 --arg3 valueA --arg3 valueB arg2Value\nconst simulatedArgs = ['node', 'my-cli.js', '--arg1', '--arg3', 'valueA', '--arg3', 'valueB', 'arg2Value'];\n\nconst myArgs = parseArgs(\n    simulatedArgs, // In a real CLI, use process.argv\n    {\n        arg1: {\n            flag: {\n                valueRequirement: FlagRequirement.Blocked,\n                description: 'A simple boolean flag.'\n            }\n        },\n        arg2: {\n            required: true,\n            position: 0,\n            description: 'A required positional argument.'\n        },\n        arg3: {\n            flag: {\n                aliases: ['-3'],\n                allowMultiple: true,\n                valueRequirement: FlagRequirement.Required,\n                description: 'A flag that can be provided multiple times.'\n            }\n        },\n        rest: {\n            position: 'rest',\n            description: 'Any remaining positional arguments.'\n        }\n    },\n    {\n        binName: 'my-cli.js', // Or the actual binary name if using a 'bin' entry in package.json\n        importMeta: import.meta,\n    },\n);\n\nconsole.log('Parsed Arguments:');\nconsole.log(`arg1: ${myArgs.arg1} (type: ${typeof myArgs.arg1})`); // boolean\nconsole.log(`arg2: ${myArgs.arg2} (type: ${typeof myArgs.arg2})`); // string\nconsole.log(`arg3: ${JSON.stringify(myArgs.arg3)} (type: ${typeof myArgs.arg3})`); // string[]\nconsole.log(`rest: ${JSON.stringify(myArgs.rest)}`); // string[]\n\n// Example: Accessing a non-existent arg will result in a TypeScript error and runtime undefined\n// console.log(myArgs.nonExistentArg); // TS Error: Property 'nonExistentArg' does not exist on type '{ arg1: boolean; arg2: string; arg3: string[]; rest: string[]; }'.\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Update `ParsedArg` to `ParsedArgs` in your type annotations: `import type { ParsedArgs } from 'cli-vir';`","message":"The `ParsedArg` type was renamed to `ParsedArgs`. If you were explicitly typing your parsed arguments, you must update the type name.","severity":"breaking","affected_versions":">=0.1.1"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<22"},{"fix":"Always provide `{ importMeta: import.meta }` in the options object when calling `parseArgs` from your main CLI entry point.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to use `require()` syntax for `cli-vir`, which is an ESM-first module.","error":"TypeError: parseArgs is not a function"},{"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).","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.","error":"TS2345: Argument of type 'string' is not assignable to parameter of type 'boolean'."},{"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.","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.","error":"ReferenceError: import_meta is not defined"}],"ecosystem":"npm","meta_description":null}