cli-options/README.md

A simple command-line argument parser for Node.js applications.

# 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

```bash
npm install parseargs
```

## Quick Start

```javascript
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:**
```bash
node myapp.js data.txt --verbose
node myapp.js --help
```

## Usage Examples

### Multiple Positional Arguments

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

**Command line usage:**
```bash
node myapp.js input.txt output.txt --force
```

### Custom Help Configuration

```javascript
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

```javascript
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:

```javascript
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:

```javascript
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:

```typescript
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](https://github.com/dtempx/parseargs)
- **Issues**: [https://github.com/dtempx/parseargs/issues](https://github.com/dtempx/parseargs/issues)