arg

library0.0.1jsnpmunverified

arg is a minimalist, unopinionated command-line argument parser for Node.js applications. It focuses on providing a straightforward API for defining and parsing CLI options, including type conversion (String, Number, Boolean, custom functions), flag counting (e.g., `--verbose -vvv`), and aliasing. The current stable version is 5.0.2, with recent patch releases addressing type fixes and dependency updates, while major releases are infrequent but cautious, aiming for minimal disruption. It prioritizes simplicity and direct mapping of arguments to values, leaving validation and requirement checking to the application layer. This makes it suitable for projects needing a lightweight parsing solution without bundled opinionated features common in larger CLI frameworks.

npm install arg

github ↗package ↗

INSTALL

IMPORT

SIG · ARG

arg

javascriptv0.0.1

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.

arg

✓ import arg from 'arg';

✗ const arg = require('arg');

ESM is preferred in modern Node.js. CommonJS `require` is also supported for older environments.

arg.COUNT

✓ import arg from 'arg'; // arg.COUNT

Used as a type function within the spec object to count flag occurrences (e.g., -v, -vv, -vvv).

arg.flag

✓ import arg from 'arg'; // arg.flag(myHandler)

A helper to mark a custom type handler as a boolean-like flag that does not consume a value.

ArgError

✓ import { ArgError } from 'arg';

✗ import arg from 'arg'; // new arg.ArgError(...)

Exported as a named export since v5.0.0 for type checking errors thrown by `arg`.

Demonstrates basic setup with type definitions, option parsing (including counts and arrays), aliases, and basic error handling.

import arg from 'arg'; type Args = { '--help': boolean; '--version': boolean; '--verbose': number; '--port': number; '--name': string; '--tag': string[]; '-v': string; '-n': string; '--label': string; _?: string[]; }; try { const args = arg<Args>( { '--help': Boolean, '--version': Boolean, '--verbose': arg.COUNT, '--port': Number, '--name': String, '--tag': [String], '-v': '--verbose', '-n': '--name', '--label': '--name' }, { argv: process.argv.slice(2), // Defaults to process.argv.slice(2) permissive: false, stopAtPositional: false } ); if (args['--help']) { console.log('Usage: my-cli [--help] [--version] [--verbose] [--port <num>] [--name <str>] [--tag <str>...]'); process.exit(0); } console.log('Parsed arguments:', args); console.log('Positional arguments (_):', args._); console.log('Verbose level:', args['--verbose']); console.log('Port:', args['--port']); console.log('Name:', args['--name']); console.log('Tags:', args['--tag']); } catch (e: any) { if (e.code === 'ARG_UNKNOWN_OPTION') { console.error(`Error: ${e.message}`); process.exit(1); } else if (e.code === 'ARG_MISSING_VALUE') { console.error(`Error: ${e.message}`); process.exit(1); } else { console.error('An unexpected error occurred:', e); process.exit(1); } }

Debug

Known issues

breakingSince v5.0.0, all errors thrown by `arg` are now instances of `require('arg').ArgError` (or `import { ArgError } from 'arg'`). If your codebase checked `error.name` or `error.constructor` for specific error types, you will need to update these checks to use `ArgError`.

fix

Update error handling logic to check `e.code` for specific error types (e.g., 'ARG_UNKNOWN_OPTION') or `e instanceof ArgError` for general `arg`-related errors.

affects: >=5.0.0

breakingStarting with v3.0.0, all properties defined in the argument specification object must begin with a hyphen (e.g., `--foo`, `-b`). Specifying a key without a hyphen (e.g., `foo: String`) will result in an error.

fix

Ensure all keys in your argument specification object (the first argument to `arg()`) are properly prefixed with one or two hyphens.

affects: >=3.0.0

gotchaBoolean and `[Boolean]` types, along with `arg.flag()`, are treated as 'flags'. This means they do not consume the subsequent command-line argument as their value. If you expect a value after a boolean flag, it will be treated as a positional argument or another option.

fix

Use `String`, `Number`, or a custom type function for options that require a value. Only use `Boolean`, `[Boolean]`, or `arg.flag()` for options that are presence-based switches.

affects: >=1.0.0

gotchaAll unconsumed command-line arguments (positional arguments) are collected into an array assigned to the `_` key in the returned object. If your application expects positional arguments, you must explicitly handle this `_` array.

fix

Access `parsedArgs._` to retrieve any non-option arguments. Remember that `_` is always an array, even if empty.

affects: >=0.2.0

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use `const arg = require('arg');` in a JavaScript module that is treated as an ES module (e.g., in a package with `"type": "module"` or a `.mjs` file).

fix

Change the import statement to `import arg from 'arg';` and run your script as an ES module.

Error: Unknown or unexpected option: --some-undefined-option

The command-line option `--some-undefined-option` was passed but is not defined in the `arg` specification object, and `permissive: false` is either explicitly set or is the default.

fix

Define `--some-undefined-option` in the `arg` specification object, or set `permissive: true` in the options object if you want to allow unknown options (they will be added to `_`).

Error: Argument is missing for --option-with-value

An option was defined with a type that expects a value (e.g., `Number`, `String`), but no value was provided for that option on the command line.

fix

Ensure that options expecting values are followed by a value (e.g., `--port 8080` or `--port=8080`). If the option should be a flag without a value, change its type to `Boolean` or use `arg.COUNT` or `arg.flag()`.

Upgrade

Version history

0.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/vercel/arg ↗

packagehttps://www.npmjs.com/package/arg ↗