{"id":12827,"library":"argue-cli","title":"argue-cli","description":"argue-cli is a lightweight and strongly typed command-line argument parser designed specifically for Node.js environments. It provides a declarative API for defining expected arguments and options, including aliases and type assertions for option values. The current stable version is 2.1.0, with a recent major release (v2.0.0) indicating ongoing development, though a fixed release cadence isn't specified. Its key differentiators lie in its \"thin\" design, aiming for minimal overhead, and its robust TypeScript support, which enables compile-time checking of CLI argument parsing logic. This helps developers avoid common runtime errors associated with loosely typed argument parsers by enforcing argument structures and types upfront. It focuses on explicitly consuming arguments with methods like `read`, `expect`, and `end`, ensuring all arguments are processed or an error is thrown for unexpected input.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/TrigenSoftware/Argue","tags":["javascript","cli","arguments","parser","console","terminal","typescript"],"install":[{"cmd":"npm install argue-cli","lang":"bash","label":"npm"},{"cmd":"yarn add argue-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add argue-cli","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v2.0.0, argue-cli is primarily an ES Module. Avoid CommonJS `require()`.","wrong":"const read = require('argue-cli').read","symbol":"read","correct":"import { read } from 'argue-cli'"},{"note":"`expect` is a named export, not a default export.","wrong":"import expect from 'argue-cli'","symbol":"expect","correct":"import { expect } from 'argue-cli'"},{"note":"`readOptions` is commonly used with `option` and `alias`, which can be imported in a single statement for brevity.","wrong":"import { readOptions } from 'argue-cli'; import { option } from 'argue-cli';","symbol":"readOptions","correct":"import { readOptions, option, alias } from 'argue-cli'"}],"quickstart":{"code":"import { read, end, expect, alias, option, readOptions } from 'argue-cli'\n\n/**\n * Expect and read one of the commands\n */\nconst command = expect(\n  alias('install', 'i'),\n  'remove'\n)\nlet options = {}\n\nif (command === 'install') {\n  /**\n   * Read passed options\n   */\n  options = readOptions(\n    option(alias('save', 'S'), Boolean),\n    option(alias('saveDev', 'save-dev', 'D'), Boolean),\n    option('workspace', String)\n  )\n}\n\n/**\n * Read next argument\n */\nconst packageName = read()\n\n/**\n * Expect end of the arguments\n */\nend()\n\nconsole.log(`Command: ${command}`);\nconsole.log(`Package Name: ${packageName}`);\nconsole.log(`Options:`, options);\n\n// To run this code, you might simulate process.argv like:\n// process.argv = ['node', 'your-script.ts', 'install', '-S', '--workspace=my-app', 'my-package'];\n// process.argv = ['node', 'your-script.ts', 'remove', 'my-package'];","lang":"typescript","description":"This example demonstrates parsing a command (`install` or `remove`), reading associated options with aliases and explicit types, and then extracting a final argument (e.g., a package name), ensuring no unhandled arguments remain."},"warnings":[{"fix":"Convert your project to use ES Modules (`\"type\": \"module\"` in `package.json` and `import` statements) or use dynamic `import()` where `require()` is unavoidable. Ensure your Node.js version is 14.0.0 or higher.","message":"argue-cli v2.0.0 and above transitioned to a primarily ES Module (ESM) approach, significantly impacting projects using CommonJS (`require()`) or older Node.js versions. Direct `require()` statements may no longer function as expected or require careful configuration.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always ensure your parsing logic accounts for optional arguments or conditions where `read()` or `expect()` might be called without an available argument. Consider wrapping calls in `try...catch` blocks for robust error handling.","message":"Incorrect usage of `read()` or `expect()` when no more arguments are available will throw an error, as these functions explicitly require an argument to be present.","severity":"gotcha","affected_versions":"*"},{"fix":"Design your CLI parsing logic to explicitly handle all possible arguments using `read()`, `expect()`, or `readOptions()` before calling `end()`. If residual arguments are acceptable, you should avoid calling `end()` or process them explicitly beforehand.","message":"The `end()` function strictly enforces that no unparsed arguments remain. If additional arguments are present after `end()` is called, it will throw an error, preventing silent failures from unhandled CLI input.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your parsing logic is structured such that `read()` is only called when an argument is expected. You might need to check `process.argv.length` or adjust your `expect()` calls for optional arguments.","cause":"Calling `read()` when there are no more command-line arguments available to consume.","error":"Error: No next argument."},{"fix":"Review your CLI structure and parsing logic. All arguments passed to the script must be explicitly consumed by `read()`, `expect()`, or `readOptions()` before `end()` is called.","cause":"`end()` was called, but there are still unparsed arguments left in `process.argv`, indicating an unhandled CLI input.","error":"Error: Unexpected argument '<argument_value>'"},{"fix":"Ensure the argument provided on the command line matches the expected type for the `option` definition (e.g., `--port=123` for `Number`, not just `--port`).","cause":"An option was defined with a specific type (e.g., `String`, `Number`, `Boolean`), but the corresponding command-line argument's value was either missing, malformed, or could not be coerced to the specified type.","error":"TypeError: Cannot read properties of undefined (reading 'split')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null}