or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdoption-definitions.mdparsing-options.md
tile.json

tessl/npm-command-line-args

A mature, feature-complete library to parse command-line options

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/command-line-args@6.0.x

To install, run

npx @tessl/cli install tessl/npm-command-line-args@6.0.0

index.mddocs/

Command Line Args

Command Line Args is a mature, feature-complete library to parse command-line options. It supports all major command-line notation standards including short and long options, multiple values, default options, and various data types through customizable setter functions. The library offers flexible parsing modes including strict validation, partial parsing for unknown arguments, and early termination options.

Package Information

  • Package Name: command-line-args
  • Package Type: npm
  • Language: JavaScript (ES Module with CommonJS support)
  • Installation: npm install command-line-args

Core Imports

import commandLineArgs from "command-line-args";

For CommonJS:

const commandLineArgs = require("command-line-args");

Basic Usage

import commandLineArgs from "command-line-args";

// Define your options
const optionDefinitions = [
  { name: 'verbose', alias: 'v', type: Boolean },
  { name: 'src', type: String, multiple: true, defaultOption: true },
  { name: 'timeout', alias: 't', type: Number }
];

// Parse command line arguments
const options = commandLineArgs(optionDefinitions);

// For input: --verbose --timeout=1000 file1.js file2.js
// Result: { verbose: true, timeout: 1000, src: ['file1.js', 'file2.js'] }

Architecture

Command Line Args is built around several key components:

  • Main Parser Function: commandLineArgs() function that orchestrates the parsing process
  • Option Definitions: Configuration objects that describe expected command-line options
  • Flexible Type System: Built-in types (String, Number, Boolean) and custom setter functions
  • Multiple Parsing Modes: Strict, partial, and stop-at-first-unknown parsing strategies
  • Value Collection: Support for single values, multiple values, and default option collection

Capabilities

Main Parser Function

Core parsing function that processes command-line arguments according to provided option definitions.

/**
 * Parse command-line arguments according to option definitions
 * @param {Array<OptionDefinition>} optionDefinitions - Array of option definition objects
 * @param {object} [options] - Parsing options
 * @param {string[]} [options.argv] - Array of strings to parse instead of process.argv
 * @param {boolean} [options.partial] - Return unknown arguments in _unknown property
 * @param {boolean} [options.stopAtFirstUnknown] - Stop parsing at first unknown argument
 * @param {boolean} [options.camelCase] - Convert hyphenated option names to camelCase
 * @param {boolean} [options.caseInsensitive] - Parse options case-insensitively
 * @returns {object} Parsed command line options
 * @throws {Error} UNKNOWN_OPTION, UNKNOWN_VALUE, ALREADY_SET, INVALID_DEFINITIONS
 */
function commandLineArgs(optionDefinitions, options);

Option Definition Configuration

Comprehensive option definition system for describing command-line arguments with validation, type conversion, and collection behaviors.

interface OptionDefinition {
  name: string;                    // Option name (required)
  type?: function;                 // Type converter function (default: String)
  alias?: string;                  // Single character short alias
  multiple?: boolean;              // Allow multiple values (greedy parsing)
  lazyMultiple?: boolean;          // Allow multiple values (non-greedy parsing)
  defaultOption?: boolean;         // Collect unaccounted values
  defaultValue?: any;              // Initial value for the option
  group?: string | string[];       // Group name(s) for organizing output
}

Option Definitions

Advanced Parsing Options

Flexible parsing modes and configuration options for handling different command-line argument scenarios.

interface ParseOptions {
  argv?: string[];               // Custom argv array (default: process.argv)
  partial?: boolean;             // Collect unknown args in _unknown property
  stopAtFirstUnknown?: boolean;  // Stop parsing at first unknown arg
  camelCase?: boolean;           // Convert hyphenated names to camelCase
  caseInsensitive?: boolean;     // Case-insensitive option matching
}

Parsing Options

Error Handling

Command Line Args throws specific error types for different validation failures:

// Error types thrown by commandLineArgs()
class CLAError extends Error {
  name: 'UNKNOWN_OPTION' | 'UNKNOWN_VALUE' | 'ALREADY_SET' | 'INVALID_DEFINITIONS';
  optionName?: string;  // For UNKNOWN_OPTION and ALREADY_SET
  value?: any;          // For UNKNOWN_VALUE and ALREADY_SET
}

Error Types:

  • UNKNOWN_OPTION: Unknown option specified (when partial=false)
  • UNKNOWN_VALUE: Unknown value specified (when partial=false)
  • ALREADY_SET: Singular option set multiple times
  • INVALID_DEFINITIONS: Invalid option definition properties

Types

/**
 * Built-in type converter functions
 */
const String: (value: any) => string;
const Number: (value: any) => number;
const Boolean: (value: any) => boolean;

/**
 * Output formats based on grouping
 */
interface StandardOutput {
  [optionName: string]: any;
  _unknown?: string[];  // Present when partial=true and unknown args found
}

interface GroupedOutput {
  _all: StandardOutput;     // All options
  _none?: StandardOutput;   // Options without group property
  _unknown?: string[];      // Unknown arguments (when partial=true)
  [groupName: string]: StandardOutput;  // Named groups
}