parseargs

A simple, lightweight command-line argument parser for Node.js applications with built-in validation and automatic help generation.

Features

• 🚀 Simple API - Easy to use with minimal configuration
• ✅ Argument Validation - Automatically validates required and optional arguments
• 📖 Auto-generated Help - Generates help text from your argument definitions
• 🔢 Positional Arguments - Support for positional file arguments
• 🏷️ Named Arguments - Support for --flag style arguments
• 🎯 TypeScript Support - Full TypeScript definitions included
• 🪶 Lightweight - Minimal dependencies (only word-wrap)

Installation

npm install parseargs

Quick Start

import { parseArgs } from 'parseargs';

const args = parseArgs({
    required: {
        0: "input file to process"
    },
    optional: {
        verbose: "enable verbose logging"
    }
});

console.log(`Processing file: ${args[0]}`);
if (args.verbose) {
    process.env.VERBOSE = '1';
    console.log('Verbose mode enabled');
}

Command line usage:

node myapp.js data.txt --verbose
node myapp.js --help

Usage Examples

Multiple Positional Arguments

const args = parseArgs({
    required: {
        0: "source file",
        1: "destination file"
    },
    optional: {
        force: "overwrite existing files",
        quiet: "suppress output"
    }
});

Command line usage:

node myapp.js input.txt output.txt --force

Custom Help Configuration

const args = parseArgs({
    required: {
        0: "configuration file"
    },
    optional: {
        port: "server port number",
        host: "server hostname"
    },
    help: {
        short: "A simple web server application",
        long: "This application starts a web server using the provided configuration file. You can customize the host and port using the optional arguments.",
        usage: "config.json [--port=3000] [--host=localhost]"
    }
});

Argument Validation

const args = parseArgs({
    required: {
        0: "input file"
    },
    optional: {
        threads: "number of threads"
    },
    validate: (args) => {
        if (args.threads && isNaN(parseInt(args.threads))) {
            return "threads must be a number";
        }
    }
});

API Reference

parseArgs(options)

Parses command-line arguments and returns an object containing the parsed values.

Parameters

• options (object) - Configuration object with the following properties:

Options

| Property | Type | Description | |----------|------|-------------| | required | object | Required arguments. Keys can be numbers (for positional args) or strings (for named args) | | optional | object | Optional arguments. Keys can be numbers (for positional args) or strings (for named args) | | help | object | Help configuration (see Help Configuration below) | | validate | function | Custom validation function that receives parsed args and returns error message or undefined |

Help Configuration

| Property | Type | Description | |----------|------|-------------| | short | string | Short description displayed in help | | long | string | Detailed description displayed in help | | usage | string \| boolean | Custom usage string or true for auto-generated usage | | params | boolean | Whether to show parameter descriptions (default: true) |

Return Value

Returns an object where:

• Positional arguments are accessible by numeric keys (args[0], args[1], etc.)
• Named arguments are accessible by their names (args.debug, args.output, etc.)
• All values are strings

Error Handling

The function will automatically:

• Display help and exit when --help is passed
• Display error message and exit when required arguments are missing
• Display error message and exit when invalid arguments are provided
• Display error message and exit when custom validation fails

Argument Types

Positional Arguments

Positional arguments are defined using numeric keys and are accessed the same way:

const args = parseArgs({
    required: {
        0: "first file",
        1: "second file"
    }
});

// Access: args[0], args[1]

Named Arguments

Named arguments use the -- prefix on the command line:

const args = parseArgs({
    optional: {
        output: "output file path",
        verbose: "enable verbose mode"
    }
});

// Command line: --output=file.txt --verbose
// Access: args.output, args.verbose

Named arguments can be specified as:

• --flag (sets value to "1")
• --flag=value (sets value to "value")

TypeScript Support

The library includes full TypeScript definitions:

import { parseArgs, ParseArgsOptions } from 'parseargs';

const options: ParseArgsOptions = {
    required: {
        0: "input file"
    },
    optional: {
        debug: "debug mode"
    }
};

const args: Record<string, string> = parseArgs(options);

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Repository

• GitHub: https://github.com/dtempx/parseargs
• Issues: https://github.com/dtempx/parseargs/issues