### Complete CLI Tool Example - peowly

Source: https://context7.com/voxpelli/peowly/llms.txt

A full-featured CLI application demonstrating flag parsing, help text generation, error handling, and proper exit codes. This example showcases best practices for building production-ready command-line tools with peowly.

```javascript
import { readFileSync } from 'node:fs';
import { peowly, formatHelpMessage } from 'peowly';

// Load package.json for metadata
const pkg = JSON.parse(readFileSync('./package.json', 'utf8'));

// Define all CLI flags with groups
const flags = {
  input: {
    type: 'string',
    description: 'Input file path (required)',
    listGroup: 'File Options',
    short: 'i',
  },
  output: {
    type: 'string',
    default: 'out.js',
    description: 'Output file path',
    listGroup: 'File Options',
    short: 'o',
  },
  watch: {
    type: 'boolean',
    description: 'Watch files for changes',
    listGroup: 'Development',
    short: 'w',
  },
  minify: {
    type: 'boolean',
    description: 'Minify the output',
    listGroup: 'Production',
    short: 'm',
  },
  sourcemap: {
    type: 'boolean',
    description: 'Generate source maps',
    listGroup: 'Production',
  },
  target: {
    type: 'string',
    default: 'es2020',
    description: 'JavaScript target version',
    listGroup: 'Production',
  },
  verbose: {
    type: 'boolean',
    description: 'Verbose logging',
  },
};

// Generate help text
const name = 'my-bundler';
const help = formatHelpMessage(name, {
  flags,
  usage: '[options]',
  examples: [
    '--input src/index.js --output dist/bundle.js',
    '--input src/app.js --minify --sourcemap',
    '--watch --verbose',
  ],
  indent: 2,
});

// Parse CLI arguments
const cli = peowly({
  name,
  pkg,
  help,
  options: flags,
  description: pkg.description,
});

// Validate required flags
if (!cli.flags.input) {
  console.error('Error: --input flag is required\n');
  cli.showHelp(1);
}

// Run the tool
try {
  console.log('Configuration:', cli.flags);
  console.log('Positional args:', cli.input);

  // Your tool logic here
  if (cli.flags.verbose) {
    console.log('Verbose mode enabled');
  }

  if (cli.flags.watch) {
    console.log('Watching for changes...');
  } else {
    console.log('Building...');
  }

  console.log('Success!');
  process.exit(0);
} catch (error) {
  console.error('Error:', error.message);
  process.exit(1);
}
```

--------------------------------

### formatHelpMessage() - Generate Help Text

Source: https://context7.com/voxpelli/peowly/llms.txt

Creates formatted help text for CLI tools, including usage instructions, commands, flags, and examples. Generates well-structured documentation with organized options and proper formatting.

```APIDOC
## formatHelpMessage() - Generate Help Text

### Description
Creates formatted help text for CLI tools with usage instructions, commands, flags, and examples. This function generates well-structured documentation that includes all CLI options organized into groups, with proper alignment and spacing. It automatically includes default `--help` and `--version` flags unless disabled.

### Method
`formatHelpMessage(name, config)`

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the CLI tool.

#### Request Body (config object)
- **flags** (object) - Required - An object defining the available flags (structure similar to `peowly()` options).
- **commands** (object) - Optional - An object defining available commands.
  - **description** (string) - Required - Description of the command.
  - **listGroup** (string) - Optional - The group to which the command belongs.
- **usage** (string) - Optional - The usage string for the CLI tool.
- **examples** (array) - Optional - An array of example commands.
- **indent** (number) - Optional - The number of spaces for indentation in the help text. Defaults to 2.

### Request Example
```javascript
import { formatHelpMessage } from 'peowly';

const flags = {
  input: {
    type: 'string',
    description: 'Input file path',
    listGroup: 'Input/Output',
  },
  output: {
    type: 'string',
    default: 'out.js',
    description: 'Output file path',
    listGroup: 'Input/Output',
  },
  minify: {
    type: 'boolean',
    description: 'Minify the output',
    short: 'm',
    listGroup: 'Optimization',
  },
};

const commands = {
  build: {
    description: 'Build the project',
    listGroup: 'Build Commands',
  },
  watch: {
    description: 'Watch files and rebuild',
    listGroup: 'Build Commands',
  },
};

const helpText = formatHelpMessage('my-bundler', {
  flags,
  commands,
  usage: '<command> [options]',
  examples: [
    'build --input src/index.js --output dist/bundle.js',
    'watch --minify',
  ],
  indent: 2,
});

console.log(helpText);
```

### Response
#### Success Response (string)
- **helpText** (string) - The formatted help message.

#### Response Example
```text
  Usage
    $ my-bundler <command> [options]

  Build Commands
    build   Build the project
    watch   Watch files and rebuild

  Input/Output
    --input          Input file path
    --output [out.js]  Output file path

  Optimization
    --minify  -m     Minify the output

  Options
    --help           Prints this help and exits.
    --version        Prints current version and exits.

  Examples
    $ my-bundler build --input src/index.js --output dist/bundle.js
    $ my-bundler watch --minify
```
```

--------------------------------

### Generate CLI Help Text

Source: https://context7.com/voxpelli/peowly/llms.txt

Creates formatted help text for CLI tools, including usage instructions, commands, flags, and examples. This function generates well-structured documentation with organized options and proper alignment. Dependencies: 'peowly' library. Input: tool name, configuration object. Output: formatted help text string.

```javascript
import { formatHelpMessage } from 'peowly';

const flags = {
  input: {
    type: 'string',
    description: 'Input file path',
    listGroup: 'Input/Output',
  },
  output: {
    type: 'string',
    default: 'out.js',
    description: 'Output file path',
    listGroup: 'Input/Output',
  },
  minify: {
    type: 'boolean',
    description: 'Minify the output',
    short: 'm',
    listGroup: 'Optimization',
  },
};

const commands = {
  build: {
    description: 'Build the project',
    listGroup: 'Build Commands',
  },
  watch: {
    description: 'Watch files and rebuild',
    listGroup: 'Build Commands',
  },
};

const helpText = formatHelpMessage('my-bundler', {
  flags,
  commands,
  usage: '<command> [options]',
  examples: [
    'build --input src/index.js --output dist/bundle.js',
    'watch --minify',
  ],
  indent: 2,
});

console.log(helpText);
// Output:
//   Usage
//     $ my-bundler <command> [options]
//
//   Build Commands
//     build   Build the project
//     watch   Watch files and rebuild
//
//   Input/Output
//     --input          Input file path
//     --output [out.js]  Output file path
//
//   Optimization
//     --minify  -m     Minify the output
//
//   Options
//     --help           Prints this help and exits.
//     --version        Prints current version and exits.
//
//   Examples
//     $ my-bundler build --input src/index.js --output dist/bundle.js
//     $ my-bundler watch --minify

```

--------------------------------

### Initialize Peowly Parser with Options

Source: https://github.com/voxpelli/peowly/blob/main/README.md

This snippet demonstrates how to initialize the peowly CLI parser with custom options, including defining flags with descriptions and types. It shows how to access the parsed flags from the returned object. Dependencies include the 'peowly' package.

```javascript
const { flags } = peowly({
  options: {
    fix: {
      description: 'Fixes stuff',
      type: 'boolean',
    },
  },
});
```

--------------------------------

### Default Help and Version Flags - peowly

Source: https://context7.com/voxpelli/peowly/llms.txt

Provides predefined flag definitions for standard --help and --version options. These are automatically included unless disabled. They ensure consistent behavior across peowly CLI tools.

```javascript
import { defaultFlags, peowly } from 'peowly';

// defaultFlags contains:
// {
//   help: {
//     default: false,
//     description: 'Prints this help and exits.',
//     type: 'boolean',
//   },
//   version: {
//     default: false,
//     description: 'Prints current version and exits.',
//     type: 'boolean',
//   },
// }

// Use with custom flags
const cli = peowly({
  options: {
    ...defaultFlags,
    custom: {
      type: 'string',
      description: 'Custom option',
    },
  },
  pkg: { version: '1.0.0' },
});

// Or exclude default flags
const cliNoDefaults = peowly({
  options: {
    custom: {
      type: 'string',
      description: 'Custom option',
    },
  },
  noDefaultFlags: true,
});
```

--------------------------------

### Format Generic Help List with Alignment (JavaScript)

Source: https://context7.com/voxpelli/peowly/llms.txt

Formats any list of items with descriptions into aligned help text. Unlike `formatFlagList()`, this function does not add any default prefix, making it suitable for formatting commands, aliases, or any custom list items that don't follow the flag convention. It accepts a list of items, indentation, and options for prefixing and padding.

```javascript
import { formatHelpList } from 'peowly';

const commands = {
  start: 'Start the development server',
  build: 'Build for production',
  test: 'Run test suite',
  deploy: 'Deploy to production',
};

const helpList = formatHelpList(commands, 4, {
  keyPrefix: '',
  padName: 12,
});

console.log(helpList);
// Output:
//     build       Build for production
//     deploy      Deploy to production
//     start       Start the development server
//     test        Run test suite
```

--------------------------------

### Initialize Peowly CLI Parser

Source: https://context7.com/voxpelli/peowly/llms.txt

Parses command-line arguments using peowly. This function accepts a configuration object defining the CLI tool's behavior, flags, and metadata. It automatically handles help and version display, validates arguments, and provides type-safe flag access. Dependencies: 'peowly' library. Input: configuration object. Output: parsed flags, positional inputs, and helper functions.

```javascript
import { peowly } from 'peowly';

const options = {
  output: {
    type: 'string',
    default: 'dist.js',
    description: 'The output file',
    listGroup: 'Output',
  },
  fix: {
    type: 'boolean',
    default: false,
    description: 'Automatically fix issues',
    short: 'f',
  },
  verbose: {
    type: 'boolean',
    description: 'Enable verbose logging',
  },
  include: {
    type: 'string',
    multiple: true,
    description: 'Files to include',
  },
};

const cli = peowly({
  name: 'my-tool',
  options,
  pkg: {
    name: 'my-tool',
    version: '1.0.0',
    description: 'A powerful CLI tool',
  },
  usage: '<command> [options]',
  examples: [
    'build --fix',
    { prefix: 'DEBUG=*', suffix: 'test --verbose' },
  ],
});

// cli.flags contains parsed flags: { output: 'dist.js', fix: false, verbose: undefined, include: undefined }
// cli.input contains positional arguments: ['build']
// cli.remainderArgs contains unparsed remainder args (if returnRemainderArgs: true)
// cli.showHelp(code) prints help and exits with specified code
```

--------------------------------

### Format Flag List with Alignment (JavaScript)

Source: https://context7.com/voxpelli/peowly/llms.txt

Formats a list of flags into human-readable help text with consistent alignment. This utility adds the `--` prefix to all flag names and handles short flag notation, default values, and proper spacing between flag names and descriptions. It takes a flags object, indentation level, and optional formatting options as input.

```javascript
import { formatFlagList } from 'peowly';

const flags = {
  config: {
    type: 'string',
    description: 'Configuration file path',
    short: 'c',
  },
  watch: {
    type: 'boolean',
    description: 'Watch mode',
    short: 'w',
  },
  port: {
    type: 'string',
    default: '3000',
    description: 'Server port',
  },
};

const flagList = formatFlagList(flags, 2, { padName: 20 });

console.log(flagList);
// Output:
// --config  -c        Configuration file path
// --port [3000]       Server port
// --watch  -w         Watch mode
```

--------------------------------

### Format Help List (TypeScript)

Source: https://github.com/voxpelli/peowly/blob/main/README.md

Formats a help list of flags with indentation and customizable options. It takes a HelpList object, an indentation level, and optional HelpListOptions for padding and prefixes. This function is typically used as a base for other formatting functions.

```typescript
function formatHelpList(list: HelpList, indent: number, options?: HelpListOptions): string
```

--------------------------------

### peowly() - Main CLI Parser

Source: https://context7.com/voxpelli/peowly/llms.txt

Parses command-line arguments and returns parsed flags, positional inputs, and helper functions. Accepts a configuration object to define the CLI tool's behavior, flags, and metadata.

```APIDOC
## peowly() - Main CLI Parser

### Description
Parses command-line arguments and returns parsed flags, positional inputs, and helper functions. The function accepts a configuration object defining the CLI tool's behavior, flags, and metadata. It automatically handles help and version display, validates arguments, and provides type-safe flag access.

### Method
`peowly(config)`

### Parameters
#### Request Body (config object)
- **name** (string) - Required - The name of the CLI tool.
- **options** (object) - Required - An object defining the available flags.
  - **type** (string) - Required - The data type of the flag (e.g., 'string', 'boolean').
  - **default** (any) - Optional - The default value for the flag.
  - **description** (string) - Required - A description of the flag.
  - **listGroup** (string) - Optional - The group to which the flag belongs in the help text.
  - **short** (string) - Optional - A single-character alias for the flag.
  - **multiple** (boolean) - Optional - If true, the flag can accept multiple values.
- **pkg** (object) - Optional - Package information for version and description.
  - **name** (string) - Required - The package name.
  - **version** (string) - Required - The package version.
  - **description** (string) - Optional - The package description.
- **usage** (string) - Optional - The usage string for the CLI tool.
- **examples** (array) - Optional - An array of example commands.

### Request Example
```javascript
import { peowly } from 'peowly';

const options = {
  output: {
    type: 'string',
    default: 'dist.js',
    description: 'The output file',
    listGroup: 'Output',
  },
  fix: {
    type: 'boolean',
    default: false,
    description: 'Automatically fix issues',
    short: 'f',
  },
  verbose: {
    type: 'boolean',
    description: 'Enable verbose logging',
  },
  include: {
    type: 'string',
    multiple: true,
    description: 'Files to include',
  },
};

const cli = peowly({
  name: 'my-tool',
  options,
  pkg: {
    name: 'my-tool',
    version: '1.0.0',
    description: 'A powerful CLI tool',
  },
  usage: '<command> [options]',
  examples: [
    'build --fix',
    { prefix: 'DEBUG=*', suffix: 'test --verbose' },
  ],
});
```

### Response
#### Success Response (object)
- **flags** (object) - Parsed command-line flags.
- **input** (array) - Positional arguments.
- **remainderArgs** (array) - Unparsed remainder arguments (if `returnRemainderArgs` is true in config).
- **showHelp** (function) - A function to display help text and exit.

#### Response Example
```json
{
  "flags": {
    "output": "dist.js",
    "fix": false,
    "verbose": undefined,
    "include": undefined
  },
  "input": ["build"],
  "remainderArgs": []
}
```
```

--------------------------------

### Format CLI Help Message

Source: https://github.com/voxpelli/peowly/blob/main/README.md

This snippet shows how to format a help message for a CLI application using the `formatHelpMessage` function from the 'peowly' library. It takes the command name and an optional `HelpMessageInfo` object to customize the output. The function returns a formatted string suitable for displaying help information to the user.

```typescript
import type { HelpMessageInfo } from 'peowly';

// Assuming 'peowly' is imported and available
// const peowly = require('peowly');

const commandName = 'my-cli-tool';
const helpInfo: HelpMessageInfo = {
  description: 'A simple CLI tool.',
  usage: '[options] <file>',
  commands: {
    'serve': { description: 'Starts a development server' },
    'build': { description: 'Builds the project' },
  },
  flags: {
    'verbose': { description: 'Enable verbose logging', type: 'boolean' },
    'port': { description: 'Port to run on', type: 'number', alias: 'p' },
  },
};

const helpText = peowly.formatHelpMessage(commandName, helpInfo);
console.log(helpText);
```

--------------------------------

### Format Grouped Generic Lists with Sections (JavaScript)

Source: https://context7.com/voxpelli/peowly/llms.txt

Creates grouped help text for any type of list items with custom grouping logic. Similar to `formatGroupedFlagList()` but without flag-specific formatting. Useful for organizing commands, subcommands, or aliases into logical sections. It takes a list of items, indentation, and options for default group names and ordering.

```javascript
import { formatGroupedHelpList } from 'peowly';

const items = {
  build: {
    description: 'Build the project',
    listGroup: 'Production',
  },
  start: {
    description: 'Start dev server',
    listGroup: 'Development',
  },
  dev: {
    description: 'Alias for start',
    listGroup: 'Development',
  },
  deploy: {
    description: 'Deploy to hosting',
    listGroup: 'Production',
  },
  help: {
    description: 'Show help',
  },
};

const grouped = formatGroupedHelpList(items, 2, {
  defaultGroupName: 'Other Commands',
  defaultGroupOrderFirst: false,
  padName: 15,
});

console.log(grouped);
// Output:
//
//   Development
//     dev            Alias for start
//     start          Start dev server
//
//   Production
//     build          Build the project
//     deploy         Deploy to hosting
//
//   Other Commands
//     help           Show help
```

--------------------------------

### Format Flag List (TypeScript)

Source: https://github.com/voxpelli/peowly/blob/main/README.md

Formats a list of flags, similar to formatHelpList, but with a default key prefix of '--'. This is useful for distinguishing flags from other command-line arguments. It utilizes the HelpList and HelpListOptions types.

```typescript
function formatFlagList(list: HelpList, indent: number, options?: HelpListOptions): string
```

--------------------------------

### Format Grouped Flag List (TypeScript)

Source: https://github.com/voxpelli/peowly/blob/main/README.md

Formats grouped help lists specifically for flags, defaulting the key prefix to '--' and the default group name to 'Options'. This streamlines the presentation of grouped command-line flags.

```typescript
formatGroupedFlagList(list: HelpList, indent: number, options?: HelpListGroupOptions): string
```

--------------------------------

### Format Grouped Help List (TypeScript)

Source: https://github.com/voxpelli/peowly/blob/main/README.md

Formats a help list with items grouped, offering additional options for controlling group display. It supports aligning items within groups and specifying default group names and order. This function enhances readability for complex command-line interfaces.

```typescript
formatGroupedHelpList(list: HelpList, indent: number, options?: HelpListGroupOptions): string
```

--------------------------------

### Format Grouped Flags with Sections (JavaScript)

Source: https://context7.com/voxpelli/peowly/llms.txt

Organizes and formats flags into categorized groups with section headers. Each flag can be assigned to a group via the `listGroup` property, and flags without a group are placed in the default 'Options' section. This function is ideal for CLIs with many flags that benefit from logical grouping. It takes flags, indentation, and options for grouping and alignment.

```javascript
import { formatGroupedFlagList } from 'peowly';

const flags = {
  input: {
    type: 'string',
    description: 'Input file',
    listGroup: 'File Options',
  },
  output: {
    type: 'string',
    description: 'Output file',
    listGroup: 'File Options',
  },
  sourcemap: {
    type: 'boolean',
    description: 'Generate sourcemap',
    listGroup: 'Build Options',
  },
  minify: {
    type: 'boolean',
    description: 'Minify output',
    listGroup: 'Build Options',
  },
  verbose: {
    type: 'boolean',
    description: 'Verbose output',
  },
};

const grouped = formatGroupedFlagList(flags, 2, {
  alignWithinGroups: true,
  defaultGroupName: 'General',
});

console.log(grouped);
// Output:
//
//   Build Options
//     --minify      Minify output
//     --sourcemap   Generate sourcemap
//
//   File Options
//     --input   Input file
//     --output  Output file
//
//   General
//     --verbose  Verbose output
```

--------------------------------

### Extract Unparsed Arguments - peowly

Source: https://context7.com/voxpelli/peowly/llms.txt

Enables the extraction of arguments that do not match defined flags. When enabled, peowly operates in non-strict mode and collects unparsed arguments in the `remainderArgs` array, useful for subcommands or wrapper scripts.

```javascript
import { peowly } from 'peowly';

const parentOptions = {
  verbose: {
    type: 'boolean',
    description: 'Verbose output',
  },
  config: {
    type: 'string',
    description: 'Config file',
  },
};

// Parse parent command args and extract remainder for child command
const parent = peowly({
  args: ['--verbose', 'subcommand', '--unknown-flag', 'value'],
  options: parentOptions,
  returnRemainderArgs: true,
});

console.log(parent.flags);
// { verbose: true, config: undefined }

console.log(parent.input);
// ['subcommand']

console.log(parent.remainderArgs);
// ['subcommand', '--unknown-flag', 'value']

// Now parse remainder args with child command parser
const childOptions = {
  'unknown-flag': {
    type: 'string',
    description: 'Child flag',
  },
};

const child = peowly({
  args: parent.remainderArgs.slice(1), // Skip 'subcommand'
  options: childOptions,
});

console.log(child.flags);
// { 'unknown-flag': 'value' }
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.