cli-nano 1.1.2 → 1.2.0

package/README.md

@@ -9,11 +9,11 @@
 
 ## cli-nano
 
-Simple library to create command-line tool (aka CLI) which is quite similar to [`Yargs`](https://github.com/yargs/yargs), it is as configurable as Yargs but is a fraction of its size. The library is also inspired by NodeJS `parseArgs()` but is again more configurable so that we really get what we would expect from a more complete CLI builder.
+Small library to create command-line tool (aka CLI) which is quite similar to [`Yargs`](https://github.com/yargs/yargs), it is as configurable as Yargs but is a fraction of its size. The library is also inspired by NodeJS `parseArgs()` but is a lot more configurable in order to get what we would expect from a more complete CLI builder tool.
 
 ### Features
 - Parses arguments
-- Supports defining Positional arguments 
+- Supports defining Positional (input) arguments
   - Supports Variadic args (1 or more positional args)
 - Automatically converts flags to camelCase to match config options
   - accepts both `--camelCase` and `--kebab-case`
@@ -22,6 +22,7 @@ Simple library to create command-line tool (aka CLI) which is quite similar to [
 - Outputs description and supplied help text by using `--help`
 - Supports defining `required` options
 - Supports `default` values
+- Supports `group` for grouping command options in help
 - No dependencies!
 
 ### Install
@@ -39,11 +40,18 @@ import { type Config, parseArgs } from 'cli-nano';
 const config: Config = {
   command: {
     name: 'serve',
-    description: 'Start a server with the given options',
+    describe: 'Start a server with the given options',
+    examples: [
+      { cmd: '$0 ./www/index.html 8080 --open', describe: 'Start web server on port 8080 and open browser' },
+      {
+        cmd: '$0 ./index.html 8081 --no-open --verbose',
+        describe: 'Start web server on port 8081 without opening browser and print more debugging logging to the console',
+      },
+    ],
     positionals: [
       {
         name: 'input',
-        description: 'serving files or directory',
+        describe: 'serving files or directory',
         type: 'string',
         variadic: true, // 1 or more
         required: true,
@@ -51,62 +59,77 @@ const config: Config = {
       {
         name: 'port',
         type: 'number',
-        description: 'port to bind on',
+        describe: 'port to bind on',
         required: false,
         default: 5000, // optional default value
-      },      
+      },
     ],
   },
   options: {
     dryRun: {
       alias: 'd',
       type: 'boolean',
-      description: 'Show what would be done, but do not actually start the server',
+      describe: 'Show what would be done, but do not actually start the server',
       default: false, // optional default value
     },
+    display: {
+      group: 'Advanced Options',
+      alias: 'D',
+      required: true,
+      type: 'boolean',
+      describe: 'a required display option',
+    },
     exclude: {
       alias: 'e',
       type: 'array',
-      description: 'pattern or glob to exclude (may be passed multiple times)',
-    },
-    rainbow: {
-      type: 'boolean',
-      alias: 'r',
-      description: 'Enable rainbow mode',
-      default: true,
+      describe: 'pattern or glob to exclude (may be passed multiple times)',
     },
     verbose: {
       alias: 'V',
       type: 'boolean',
-      description: 'print more information to console',
+      describe: 'print more information to console',
+    },
+    open: {
+      alias: 'o',
+      type: 'boolean',
+      describe: 'open browser when starting server',
+      default: true,
     },
-    up: {
+    cache: {
       type: 'number',
-      description: 'slice a path off the bottom of the paths',
-      default: 1,
+      describe: 'Set cache time (in seconds) for cache-control max-age header',
+      default: 3600,
     },
-    display: {
-      alias: 'D',
+    address: {
+      type: 'string',
+      describe: 'Address to use',
       required: true,
+    },
+    rainbow: {
+      group: 'Advanced Options',
       type: 'boolean',
-      description: 'a required display option',
-    }
+      alias: 'r',
+      describe: 'Enable rainbow mode',
+      default: true,
+    },
   },
   version: '0.1.6',
-  helpOptLength: 18,  // option name length shown in help (defaults to 20)
-  helpDescLength: 60, // description length shown in help (defaults to 65)
+  helpFlagCasing: 'camel',  // show help flag option in which casing (camel/kebab) (defaults to 'kebab')
+  helpDescMinLength: 40,    // min description length shown in help (defaults to 50)
+  helpDescMaxLength: 120,   // max description length shown in help (defaults to 100), will show ellipsis (...) when greater
 };
 
 const args = parseArgs(config);
 console.log(args);
 
-// do something with parse arguments, for example
-// startServer(args);
+// do something with parsed arguments, for example
+// const { input, port, open } = args;
+// startServer({ input, port, open });
 ```
 
 ### Usage with Type Inference
 
-For full TypeScript auto-inference and IntelliSense of parsed arguments, define your config as a `const` and use `as const`:
+For full TypeScript auto-inference and intelliSense of parsed arguments, define your config as a `const` and cast it `as const`:
 
 ```ts
 const config = {
@@ -124,10 +147,10 @@ args.display; // boolean (required)
 
 > **Tip:**  
 > Using `as const` preserves literal types and tuple information, so TypeScript can infer required/optional fields and argument types automatically.  
-> If you use `const config: Config = { ... }`, you get type checking but not full IntelliSense for parsed arguments.
+> If you use `const config: Config = { ... }`, you get type checking but not full intelliSense for parsed arguments.
 
 > [!NOTE]
-> For required+variadic positionals, the type is `[string, ...string[]]` (at least one value required). For optional variadic, it's string[]. For non-variadic, it's string.
+> For required+variadic positionals, the type is `[string, ...string[]]` (at least one value required). For optional variadic, it's `string[]`. For non-variadic, it's `string`.
 
 #### Example CLI Calls
 
@@ -144,13 +167,13 @@ serve dist/index.html
 # With required and optional positionals
 serve index1.html index2.html 8080 -D value
 
-# With boolean and array options
+# With boolean and array options entered as camelCase (kebab-case works too)
 serve index.html 7000 --dryRun --exclude pattern1 --exclude pattern2 -D value
 
-# With negated boolean
+# With negated boolean entered as kebab-case
 serve index.html 7000 --no-dryRun -D value
 
-# With short aliases
+# With short aliases (case sensitive)
 serve index.html 7000 -d -e pattern1 -e pattern2 -D value
 
 # With number option
@@ -159,7 +182,7 @@ serve index.html 7000 --up 2 -D value
 
 #### Notes
 
-- **Default values**: Use the `default` property in an option or positional argument to specify a value if the user does not provide one.
+- **Default values**: Use the `default` property in an option or positional argument to specify a value when the user does not provide one.
   - Example for option: `{ type: 'boolean', default: false }`
   - Example for positional: `{ name: 'port', type: 'number', default: 5000 }`
 - **Variadic positionals**: Use `variadic: true` for arguments that accept multiple values.
@@ -167,6 +190,7 @@ serve index.html 7000 --up 2 -D value
 - **Negated booleans**: Use `--no-flag` to set a boolean option to `false`.
 - **Array options**: Repeat the flag to collect multiple values (e.g., `--exclude a --exclude b`).
 - **Aliases**: Use `alias` for short flags (e.g., `-d` for `--dryRun`).
+- **Groups**: Use `group` for grouping some commands in help (e.g., `{ group: 'Extra Commands' }`).
 
 See [examples/](examples/) for more usage patterns.
 
@@ -179,7 +203,7 @@ See [examples/](examples/) for more usage patterns.
 
 ## Help Example
 
-You can see below an example of a CLI help (which is the result of calling `--help` with the config shown avove). 
+You can see below an example of a CLI help (which is the result of calling `--help` with the [config](#usage) shown above). 
 
 Please note:
 
@@ -188,19 +212,27 @@ Please note:
 
 ```
 Usage:
-  serve <input..> [port] [options]  Start a server with the given options
+  serve <input..> [port] [options]   Start a server with the given options
+
+Examples:
+  serve ./www/index.html 8080 --open   Start web server on port 8080 and open browser
+  serve ./index.html 8081 --no-open --verbose   Start web server on port 8081 without opening browser and print more debugging logging to the console
 
 Arguments:
-  input             serving files or directory                                   <string..>
-  port              port to bind on                                              [number]
+  input           serving files or directory                                      <string..>
+  port            port to bind on                                                 [number]
 
 Options:
-  -d, --dryRun      Show what would be done, but do not actually start the se... [boolean]
-  -e, --exclude     pattern or glob to exclude (may be passed multiple times)    [array]
-  -r, --rainbow     Enable rainbow mode                                          [boolean]
-  -V, --verbose     print more information to console                            [boolean]
-      --up          slice a path off the bottom of the paths                     [number]
-  -D, --display     a required display option                                    <boolean>
-  -h, --help        Show help                                                    [boolean]
-  -v, --version     Show version number                                          [boolean]
-```
+  -d, --dry-run   Show what would be done, but do not actually start the server   [boolean]
+  -e, --exclude   pattern or glob to exclude (may be passed multiple times)       [array]
+  -V, --verbose   print more information to console                               [boolean]
+  -o, --open      open browser when starting server                               [boolean]
+      --cache     Set cache time (in seconds) for cache-control max-age header    [number]
+      --address   Address to use                                                  <string>
+  -h, --help      Show help                                                       [boolean]
+  -v, --version   Show version number                                             [boolean]
+
+Advanced Options:
+  -D, --display   a required display option                                       <boolean>
+  -r, --rainbow   Enable rainbow mode                                             [boolean]
+```

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE3E,mBAAmB,iBAAiB,CAAC;AAOrC,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAgMpE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAc,MAAM,iBAAiB,CAAC;AAEtE,mBAAmB,iBAAiB,CAAC;AAOrC,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAgMpE"}

package/dist/index.js

@@ -1,6 +1,6 @@
 const defaultOptions = {
-    help: { alias: 'h', description: 'Show help', type: 'boolean' },
-    version: { alias: 'v', description: 'Show version number', type: 'boolean' },
+    help: { alias: 'h', describe: 'Show help', type: 'boolean' },
+    version: { alias: 'v', describe: 'Show version number', type: 'boolean' },
 };
 export function parseArgs(config) {
     const { command, options, version } = config;
@@ -227,22 +227,63 @@ function findOption(options, arg) {
 }
 /** Print CLI help documentation to the screen */
 function printHelp(config) {
-    const { command, options, version, helpOptLength = 20, helpDescLength = 65 } = config;
+    const { command, options, version, helpDescMinLength = 50, helpDescMaxLength = 100 } = config;
     const usagePositionals = buildUsagePositionals(command.positionals);
     console.log('Usage:');
-    console.log(`  ${command.name} ${usagePositionals} [options]  ${command.description}`);
+    console.log(`  ${command.name} ${usagePositionals} [options]   ${command.describe}`);
+    // display any examples (when provided)
+    if (Array.isArray(command.examples) && command.examples.length) {
+        console.log('\nExamples:');
+        command.examples.forEach(ex => {
+            console.log(`  ${ex.cmd.replace('$0', command.name)}   ${ex.describe || ''}`);
+        });
+    }
+    // calculate longest description length
+    let longestOptNameLn = 0;
+    let longestOptDescLn = 0;
+    for (const [key, option] of Object.entries({ ...options, ...defaultOptions })) {
+        const flagLn = (config.helpFlagCasing === 'camel' ? key : camelToKebab(key)).length;
+        if (flagLn > longestOptNameLn) {
+            longestOptNameLn = key.length;
+        }
+        if ((option.describe?.length ?? 0) > longestOptDescLn) {
+            longestOptDescLn = option.describe.length;
+        }
+    }
+    // make sure the length to use is between our defined min/max
+    if (longestOptDescLn < helpDescMinLength) {
+        longestOptDescLn = helpDescMinLength;
+    }
+    else if (longestOptDescLn > helpDescMaxLength) {
+        longestOptDescLn = helpDescMaxLength;
+    }
+    // reserve some extra spaces between option name/desc
+    longestOptDescLn += 2;
+    longestOptNameLn += 3;
     console.log('\nArguments:');
     command.positionals?.forEach(arg => {
-        console.log(`  ${formatHelpText(arg.name, helpOptLength)}${formatHelpText(arg.description, helpDescLength)} ${formatOptionType(arg.type, arg.variadic, arg.required)}`);
+        console.log(`  ${formatHelpText(arg.name, longestOptNameLn + 6)}${formatHelpText(arg.describe, longestOptDescLn)} ${formatOptionType(arg.type, arg.variadic, arg.required)}`);
     });
-    console.log('\nOptions:');
-    for (const [key, option] of Object.entries({ ...options, ...defaultOptions })) {
-        const aliasStr = option.alias ? `-${option.alias}, ` : '';
-        if (!version && key === 'version') {
-            continue;
+    // Group options by their group property
+    const groupedOptions = Object.entries({ ...options, ...defaultOptions }).reduce((acc, [key, option]) => {
+        const group = option.group || 'Options';
+        if (!acc[group]) {
+            acc[group] = [];
         }
-        console.log(`  ${aliasStr.padEnd(4)}--${formatHelpText(key, helpOptLength - 6)}${formatHelpText(option.description || '', helpDescLength)} ${formatOptionType(option.type, false, option.required)}`);
-    }
+        acc[group].push([key, option]);
+        return acc;
+    }, {});
+    Object.keys(groupedOptions).forEach(group => {
+        console.log(`\n${group}:`);
+        groupedOptions[group].forEach(([key, option]) => {
+            const aliasStr = option.alias ? `-${option.alias}, ` : '';
+            if (!version && key === 'version') {
+                return;
+            }
+            const flagName = config.helpFlagCasing === 'camel' ? key : camelToKebab(key);
+            console.log(`  ${aliasStr.padEnd(4)}--${formatHelpText(flagName, longestOptNameLn)}${formatHelpText(option.describe || '', longestOptDescLn)} ${formatOptionType(option.type, false, option.required)}`);
+        });
+    });
 }
 /** Utility to convert kebab-case to camelCase */
 function kebabToCamel(str) {

package/dist/interfaces.d.ts

@@ -1,20 +1,22 @@
-export interface ArgumentOptions {
+export interface FlagOption {
     /** option type */
     type?: 'string' | 'boolean' | 'number' | 'array';
-    /** description of the flag option */
-    description: string;
+    /** describe the flag option */
+    describe: string;
     /** defaults to undefined, provide shorter alias as command options */
     alias?: string;
     /** default value for the option if not provided */
     default?: any;
+    /** optional group for grouping some commands */
+    group?: string;
     /** defaults to false, is the option required? */
     required?: boolean;
 }
 export interface PositionalArgument {
     /** positional argument name (it will be displayed in the help docs) */
     name: string;
-    /** positional argument description */
-    description: string;
+    /** describe positional argument */
+    describe: string;
     /** postional argument type */
     type?: 'string' | 'boolean' | 'number' | 'array';
     /** defaults to false, allows multiple values for this positional argument */
@@ -24,24 +26,37 @@ export interface PositionalArgument {
     /** defaults to false, is the positional argument required? */
     required?: boolean;
 }
-export interface CommandOptions {
+export interface CommandOption {
     /** command name, used in the help docs */
     name: string;
-    /** command description */
-    description: string;
+    /** describe command */
+    describe: string;
+    /** give some example invocations of your program */
+    examples?: readonly ExampleOption[];
     /** list of positional arguments */
     positionals?: readonly PositionalArgument[];
 }
+export interface ExampleOption {
+    /** script example command, the string `$0` will get interpolated to the current script name or node command */
+    cmd: string;
+    /** describe what the script command does */
+    describe: string;
+}
 /** CLI options */
 export interface Config {
     /** CLI definition */
-    command: CommandOptions;
-    /** option name length (w/wo alias) shown in the help (defaults to 20) */
-    helpOptLength?: number;
-    /** description length shown in the help (defaults to 65) */
-    helpDescLength?: number;
+    command: CommandOption;
+    /**
+     * Show flag option in which casing (camelCase or kebab-case) in the help (defaults to 'kebab').
+     * Note: this is only for the help print, the parsing will always support both camel/kebab casing
+     */
+    helpFlagCasing?: 'camel' | 'kebab';
+    /** min description length shown in the help (defaults to 50) */
+    helpDescMinLength?: number;
+    /** max description length shown in the help (defaults to 100) */
+    helpDescMaxLength?: number;
     /** CLI list of flag options */
-    options: Record<string, ArgumentOptions>;
+    options: Record<string, FlagOption>;
     /** CLI or package version */
     version?: string;
 }

package/dist/interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cli-nano",
-  "version": "1.1.2",
-  "description": "Mini command-line tool similar to `yargs` or `parseArgs` from Node.js that accepts positional arguments, flags and options.",
+  "version": "1.2.0",
+  "description": "Small command-line tool similar to `yargs` or `parseArgs` from Node.js to create a CLI accepting positional arguments, flags and options.",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -16,7 +16,8 @@
     "access": "public"
   },
   "files": [
-    "/dist"
+    "/dist",
+    "/src"
   ],
   "license": "MIT",
   "author": "Ghislain B.",

package/src/index.ts

@@ -0,0 +1,328 @@
+import type { ArgsResult, Config, FlagOption } from './interfaces.js';
+
+export type * from './interfaces.js';
+
+const defaultOptions: Record<string, FlagOption> = {
+  help: { alias: 'h', describe: 'Show help', type: 'boolean' },
+  version: { alias: 'v', describe: 'Show version number', type: 'boolean' },
+};
+
+export function parseArgs<C extends Config>(config: C): ArgsResult<C> {
+  const { command, options, version } = config;
+
+  // Normalize args to support --option=value and -o=value
+  const args = process.argv.slice(2).flatMap(arg => {
+    if (/^--?\w[\w-]*=/.test(arg)) {
+      const [flag, ...rest] = arg.split('=');
+      return [flag, rest.join('=')];
+    }
+    return arg;
+  });
+  const result: Record<string, any> = {};
+
+  // Check for duplicate aliases
+  const aliasMap = new Map<string, string>();
+  for (const [key, opt] of Object.entries(options)) {
+    if (opt.alias) {
+      if (aliasMap.has(opt.alias)) {
+        throw new Error(`Duplicate alias detected: "${opt.alias}" used for both "${aliasMap.get(opt.alias)}" and "${key}"`);
+      }
+      aliasMap.set(opt.alias, key);
+    }
+  }
+
+  // Handle --help and --version before anything else
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp(config);
+    process.exit(0);
+  }
+  if ((version && args.includes('--version')) || args.includes('-v')) {
+    console.log(version || 'No version specified');
+    process.exit(0);
+  }
+
+  // Validate: required positionals must come before optional ones
+  const positionals = command.positionals ?? [];
+  let foundOptional = false;
+  for (const pos of positionals) {
+    if (!pos.required) {
+      foundOptional = true;
+    }
+    if (foundOptional && pos.required) {
+      throw new Error(`Invalid positional argument configuration: required positional "${pos.name}" cannot follow optional positional(s).`);
+    }
+  }
+
+  // Handle positional arguments
+  let argIndex = 0;
+  const nonOptionArgs: string[] = [];
+  while (argIndex < args.length && !args[argIndex].startsWith('-')) {
+    nonOptionArgs.push(args[argIndex]);
+    argIndex++;
+  }
+
+  let nonOptionIndex = 0;
+  for (let i = 0; i < positionals.length; i++) {
+    const pos = positionals[i];
+    if (pos.variadic) {
+      const remaining = positionals.length - (i + 1);
+      const values = nonOptionArgs.slice(nonOptionIndex, nonOptionArgs.length - remaining);
+      if (pos.required && values.length === 0) {
+        const usagePositionals = buildUsagePositionals(positionals);
+        throw new Error(`Missing required positional argument, i.e.: "${command.name} ${usagePositionals}"`);
+      }
+      result[pos.name] = !pos.required && values.length === 0 && pos.default !== undefined ? pos.default : values;
+      nonOptionIndex += values.length;
+    } else {
+      const value = nonOptionArgs[nonOptionIndex];
+      // Check if there are enough args left for required positionals
+      const requiredLeft = positionals.slice(i).filter(p => p.required).length;
+      const argsLeft = nonOptionArgs.length - nonOptionIndex;
+      if (value !== undefined && (argsLeft > requiredLeft - (pos.required ? 1 : 0) || pos.required)) {
+        result[pos.name] = value;
+        nonOptionIndex++;
+      } else if (!pos.required && pos.default !== undefined) {
+        result[pos.name] = pos.default;
+      } else if (pos.required) {
+        const usagePositionals = buildUsagePositionals(positionals);
+        throw new Error(`Missing required positional argument, i.e.: "${command.name} ${usagePositionals}"`);
+      }
+    }
+  }
+
+  // Handle options
+  argIndex = 0;
+  const consumedArgs = new Set<number>();
+  // Mark all nonOptionArgs indices as consumed for positionals
+  let tempNonOptionIndex = 0;
+  for (let i = 0; i < positionals.length; i++) {
+    const pos = positionals[i];
+    if (pos.variadic) {
+      const remaining = positionals.length - (i + 1);
+      const values = nonOptionArgs.slice(tempNonOptionIndex, nonOptionArgs.length - remaining);
+      for (let j = tempNonOptionIndex; j < tempNonOptionIndex + values.length; j++) {
+        consumedArgs.add(args.findIndex((a, idx) => !a.startsWith('-') && !consumedArgs.has(idx) && a === nonOptionArgs[j]));
+      }
+      tempNonOptionIndex += values.length;
+    } else {
+      const value = nonOptionArgs[tempNonOptionIndex++];
+      consumedArgs.add(args.findIndex((a, idx) => !a.startsWith('-') && !consumedArgs.has(idx) && a === value));
+    }
+  }
+
+  while (argIndex < args.length) {
+    if (consumedArgs.has(argIndex)) {
+      argIndex++;
+      continue;
+    }
+    const argOrg = args[argIndex] || '';
+    let arg = argOrg;
+    let option: FlagOption | undefined;
+    let configKey: string | undefined;
+
+    if (argOrg.startsWith('-')) {
+      if (argOrg.startsWith('--')) {
+        arg = argOrg.slice(2);
+        [option, configKey] = findOption(options, arg);
+      } else if (argOrg.startsWith('-')) {
+        arg = argOrg.slice(1);
+        [option, configKey] = findOption(options, arg);
+      }
+
+      // Handle negated boolean in both forms
+      if (!option) {
+        const isNegated = arg.startsWith('no-');
+        const optionName = isNegated ? arg.slice(3) : arg;
+        const camelOptionName = kebabToCamel(optionName);
+        option = options[optionName] || options[camelOptionName];
+        configKey = camelOptionName in options ? camelOptionName : optionName;
+        if (option?.type === 'boolean') {
+          if (result[optionName] !== undefined || result[camelOptionName] !== undefined) {
+            throw new Error('Providing same negated and truthy argument are not allowed');
+          }
+          result[configKey] = !isNegated;
+          argIndex++;
+          continue;
+        }
+      }
+
+      if (!option || !configKey) {
+        throw new Error(`Unknown CLI option: ${arg}`);
+      }
+
+      switch (option.type) {
+        case 'boolean':
+          if (result[configKey] !== undefined) {
+            throw new Error('Providing same negated and truthy argument are not allowed');
+          }
+          result[configKey] = !argOrg.startsWith('--no-') && !argOrg.startsWith('-no-');
+          break;
+        case 'number':
+          if (args[argIndex + 1] === undefined || args[argIndex + 1].startsWith('-')) {
+            throw new Error(`Missing value for option: ${configKey}`);
+          }
+          result[configKey] = Number(args[++argIndex]);
+          break;
+        case 'array': {
+          if (!result[configKey]) result[configKey] = [];
+          const arrayValue = args[++argIndex];
+          if (arrayValue === undefined || arrayValue.startsWith('-')) {
+            throw new Error(`Missing value for array option: ${configKey}`);
+          }
+          result[configKey].push(arrayValue);
+          break;
+        }
+        case 'string':
+        default:
+          if (args[argIndex + 1] === undefined || args[argIndex + 1].startsWith('-')) {
+            throw new Error(`Missing value for option: ${configKey}`);
+          }
+          result[configKey] = args[++argIndex];
+          break;
+      }
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+    argIndex++;
+  }
+
+  // After all parsing, assign any `default` CLI options when undefined
+  // and check for any missing `required` CLI options
+  Object.entries(options).forEach(([key, opt]) => {
+    if (result[key] === undefined && opt.default !== undefined) {
+      result[key] = opt.default;
+    }
+    if (opt.required && result[key] === undefined) {
+      const aliasStr = opt.alias ? `-${opt.alias}, ` : '';
+      throw new Error(`Missing required option: ${aliasStr}--${key}`);
+    }
+  });
+
+  return result as ArgsResult<C>;
+}
+
+/** Format a text to a fixed length, truncating and padding as needed. */
+function formatHelpText(text: string, max: number) {
+  const truncated = text.length > max ? `${text.slice(0, max - 3)}...` : text;
+  return truncated.padEnd(max);
+}
+
+/** Build the usage string for positionals, e.g. "<input..> [output]" */
+function buildUsagePositionals(positionals: readonly any[] = []) {
+  return positionals
+    .map(p => {
+      const variadic = p.variadic ? '..' : '';
+      return p.required ? `<${p.name}${variadic}>` : `[${p.name}${variadic}]`;
+    })
+    .join(' ');
+}
+
+/** Format the option/argument type for help output */
+function formatOptionType(type: string | undefined, variadic?: boolean, required?: boolean) {
+  const t = type || 'string';
+  const variadicStr = variadic ? '..' : '';
+  return required ? `<${t}${variadicStr}>` : `[${t}${variadicStr}]`;
+}
+
+/** Helper to find an option and its config key by argument name or alias. */
+function findOption(options: Record<string, FlagOption>, arg: string): [FlagOption | undefined, string | undefined] {
+  // Try all forms: as-is, kebab-to-camel, camel-to-kebab
+  const option = options[arg] || options[kebabToCamel(arg)] || options[camelToKebab(arg).replace(/-/g, '')];
+  if (option) {
+    const configKey = Object.keys(options).find(key => options[key] === option);
+    return [option, configKey];
+  }
+  // Try matching alias in all forms
+  for (const key of Object.keys(options)) {
+    const opt = options[key];
+    if (opt.alias && (opt.alias === arg || opt.alias === kebabToCamel(arg) || opt.alias === camelToKebab(arg))) {
+      return [opt, key];
+    }
+  }
+  return [undefined, undefined];
+}
+
+/** Print CLI help documentation to the screen */
+function printHelp(config: Config) {
+  const { command, options, version, helpDescMinLength = 50, helpDescMaxLength = 100 } = config;
+  const usagePositionals = buildUsagePositionals(command.positionals);
+
+  console.log('Usage:');
+  console.log(`  ${command.name} ${usagePositionals} [options]   ${command.describe}`);
+
+  // display any examples (when provided)
+  if (Array.isArray(command.examples) && command.examples.length) {
+    console.log('\nExamples:');
+    command.examples.forEach(ex => {
+      console.log(`  ${ex.cmd.replace('$0', command.name)}   ${ex.describe || ''}`);
+    });
+  }
+
+  // calculate longest description length
+  let longestOptNameLn = 0;
+  let longestOptDescLn = 0;
+  for (const [key, option] of Object.entries({ ...options, ...defaultOptions })) {
+    const flagLn = (config.helpFlagCasing === 'camel' ? key : camelToKebab(key)).length;
+    if (flagLn > longestOptNameLn) {
+      longestOptNameLn = key.length;
+    }
+    if ((option.describe?.length ?? 0) > longestOptDescLn) {
+      longestOptDescLn = option.describe.length;
+    }
+  }
+
+  // make sure the length to use is between our defined min/max
+  if (longestOptDescLn < helpDescMinLength) {
+    longestOptDescLn = helpDescMinLength;
+  } else if (longestOptDescLn > helpDescMaxLength) {
+    longestOptDescLn = helpDescMaxLength;
+  }
+
+  // reserve some extra spaces between option name/desc
+  longestOptDescLn += 2;
+  longestOptNameLn += 3;
+
+  console.log('\nArguments:');
+  command.positionals?.forEach(arg => {
+    console.log(
+      `  ${formatHelpText(arg.name, longestOptNameLn + 6)}${formatHelpText(arg.describe, longestOptDescLn)} ${formatOptionType(arg.type, arg.variadic, arg.required)}`,
+    );
+  });
+
+  // Group options by their group property
+  const groupedOptions = Object.entries({ ...options, ...defaultOptions }).reduce(
+    (acc, [key, option]) => {
+      const group = option.group || 'Options';
+      if (!acc[group]) {
+        acc[group] = [];
+      }
+      acc[group].push([key, option]);
+      return acc;
+    },
+    {} as Record<string, [string, FlagOption][]>,
+  );
+
+  Object.keys(groupedOptions).forEach(group => {
+    console.log(`\n${group}:`);
+    groupedOptions[group].forEach(([key, option]) => {
+      const aliasStr = option.alias ? `-${option.alias}, ` : '';
+      if (!version && key === 'version') {
+        return;
+      }
+      const flagName = config.helpFlagCasing === 'camel' ? key : camelToKebab(key);
+      console.log(
+        `  ${aliasStr.padEnd(4)}--${formatHelpText(flagName, longestOptNameLn)}${formatHelpText(option.describe || '', longestOptDescLn)} ${formatOptionType(option.type, false, option.required)}`,
+      );
+    });
+  });
+}
+
+/** Utility to convert kebab-case to camelCase */
+function kebabToCamel(str: string) {
+  return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/** Utility to convert camelCase to kebab-case */
+function camelToKebab(str: string) {
+  return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}

package/src/interfaces.ts

@@ -0,0 +1,136 @@
+export interface FlagOption {
+  /** option type */
+  type?: 'string' | 'boolean' | 'number' | 'array';
+
+  /** describe the flag option */
+  describe: string;
+
+  /** defaults to undefined, provide shorter alias as command options */
+  alias?: string;
+
+  /** default value for the option if not provided */
+  default?: any;
+
+  /** optional group for grouping some commands */
+  group?: string;
+
+  /** defaults to false, is the option required? */
+  required?: boolean;
+}
+
+export interface PositionalArgument {
+  /** positional argument name (it will be displayed in the help docs) */
+  name: string;
+
+  /** describe positional argument */
+  describe: string;
+
+  /** postional argument type */
+  type?: 'string' | 'boolean' | 'number' | 'array';
+
+  /** defaults to false, allows multiple values for this positional argument */
+  variadic?: boolean;
+
+  /** default value for the option if not provided */
+  default?: any;
+
+  /** defaults to false, is the positional argument required? */
+  required?: boolean;
+}
+
+export interface CommandOption {
+  /** command name, used in the help docs */
+  name: string;
+
+  /** describe command */
+  describe: string;
+
+  /** give some example invocations of your program */
+  examples?: readonly ExampleOption[];
+
+  /** list of positional arguments */
+  positionals?: readonly PositionalArgument[];
+}
+
+export interface ExampleOption {
+  /** script example command, the string `$0` will get interpolated to the current script name or node command */
+  cmd: string;
+
+  /** describe what the script command does */
+  describe: string;
+}
+
+/** CLI options */
+export interface Config {
+  /** CLI definition */
+  command: CommandOption;
+
+  /**
+   * Show flag option in which casing (camelCase or kebab-case) in the help (defaults to 'kebab').
+   * Note: this is only for the help print, the parsing will always support both camel/kebab casing
+   */
+  helpFlagCasing?: 'camel' | 'kebab';
+
+  /** min description length shown in the help (defaults to 50) */
+  helpDescMinLength?: number;
+
+  /** max description length shown in the help (defaults to 100) */
+  helpDescMaxLength?: number;
+
+  /** CLI list of flag options */
+  options: Record<string, FlagOption>;
+
+  /** CLI or package version */
+  version?: string;
+}
+
+/** Utility type to map ArgumentOptions/PositionalArgument to their value type */
+export type ArgValueType<T extends { type?: string; default?: any; variadic?: boolean; required?: boolean }> = T['type'] extends 'boolean'
+  ? boolean
+  : T['type'] extends 'number'
+    ? number
+    : T['type'] extends 'array'
+      ? T extends { variadic: true }
+        ? T extends { required: true }
+          ? [string, ...string[]]
+          : string[]
+        : string | string[]
+      : T['type'] extends 'string'
+        ? T extends { variadic: true }
+          ? T extends { required: true }
+            ? [string, ...string[]]
+            : string[]
+          : string
+        : T['type'] extends undefined
+          ? T extends { variadic: true }
+            ? T extends { required: true }
+              ? [string, ...string[]]
+              : string[]
+            : string
+          : T['default'] extends undefined
+            ? string
+            : T['default'];
+
+/** Helper to get required keys */
+type RequiredKeys<T> = {
+  [K in keyof T]: T[K] extends { required: true } ? K : never;
+}[keyof T];
+
+/** Helper to get optional keys */
+type OptionalKeys<T> = Exclude<keyof T, RequiredKeys<T>>;
+
+/** Map options record to an object type with required/optional properties */
+export type OptionsToObject<T extends Record<string, any>> = { [K in RequiredKeys<T>]: ArgValueType<T[K]> } & {
+  [K in OptionalKeys<T>]?: ArgValueType<T[K]>;
+};
+
+/** Map positionals array to an object type with required/optional properties */
+export type PositionalsToObject<T extends readonly PositionalArgument[] | undefined> = T extends readonly [infer P, ...infer Rest]
+  ? P extends PositionalArgument
+    ? (P['required'] extends true ? { [K in P['name']]: ArgValueType<P> } : { [K in P['name']]?: ArgValueType<P> }) &
+        PositionalsToObject<Rest extends readonly PositionalArgument[] ? Rest : []>
+    : PositionalsToObject<Rest extends readonly PositionalArgument[] ? Rest : []>
+  : { [key: string]: never };
+
+/** The full result type for parseArgs */
+export type ArgsResult<C extends Config> = PositionalsToObject<C['command']['positionals']> & OptionsToObject<C['options']>;