or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md option-definitions.md parsing-options.md

tile.json

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
}