Registry / argue-cli

argue-cli

library2.1.0jsnpmunverified

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.

npm install argue-cli

github ↗package ↗

INSTALL

IMPORT

SIG · ARGUE-CLI

argue-cli

javascriptv2.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

read

✓ import { read } from 'argue-cli'

✗ const read = require('argue-cli').read

Since v2.0.0, argue-cli is primarily an ES Module. Avoid CommonJS `require()`.

expect

✓ import { expect } from 'argue-cli'

✗ import expect from 'argue-cli'

`expect` is a named export, not a default export.

readOptions

✓ import { readOptions, option, alias } from 'argue-cli'

✗ import { readOptions } from 'argue-cli'; import { option } from 'argue-cli';

`readOptions` is commonly used with `option` and `alias`, which can be imported in a single statement for brevity.

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.

import { read, end, expect, alias, option, readOptions } from 'argue-cli' /** * Expect and read one of the commands */ const command = expect( alias('install', 'i'), 'remove' ) let options = {} if (command === 'install') { /** * Read passed options */ options = readOptions( option(alias('save', 'S'), Boolean), option(alias('saveDev', 'save-dev', 'D'), Boolean), option('workspace', String) ) } /** * Read next argument */ const packageName = read() /** * Expect end of the arguments */ end() console.log(`Command: ${command}`); console.log(`Package Name: ${packageName}`); console.log(`Options:`, options); // To run this code, you might simulate process.argv like: // process.argv = ['node', 'your-script.ts', 'install', '-S', '--workspace=my-app', 'my-package']; // process.argv = ['node', 'your-script.ts', 'remove', 'my-package'];

argue --version

Debug

Known issues

breakingargue-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.

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.

affects: >=2.0.0

gotchaIncorrect 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.

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.

affects: *

gotchaThe `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.

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.

affects: *

Errors

Common errors & fixes

Error: No next argument.

Calling `read()` when there are no more command-line arguments available to consume.

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.

Error: Unexpected argument '<argument_value>'

`end()` was called, but there are still unparsed arguments left in `process.argv`, indicating an unhandled CLI input.

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.

TypeError: Cannot read properties of undefined (reading 'split')

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.

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`).

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/TrigenSoftware/Argue ↗

packagehttps://www.npmjs.com/package/argue-cli ↗