zod-args-parser 1.2.8 → 2.0.0-beta.0

package/README.md

@@ -4,768 +4,705 @@
 [![GitHub](https://img.shields.io/github/license/alabsi91/zod-args-parser?style=for-the-badge)](https://github.com/alabsi91/zod-args-parser/blob/main/LICENSE)
 [![GitHub issues](https://img.shields.io/github/issues/alabsi91/zod-args-parser?style=for-the-badge)](https://github.com/alabsi91/zod-args-parser/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)
 
-A strictly typed command-line arguments parser powered by [Zod](https://github.com/colinhacks/zod).
+A strictly typed command-line arguments parser powered by schema validation.
 
 ## Table of Contents
 
 - [Features](#features)
 - [Installation](#installation)
 - [Usage](#usage)
+- [Example](#example)
 - [Guide](#guide)
-  - [Subcommands](#subcommands)
-  - [Type Zod Schemas](#type-zod-schemas)
-  - [Options](#options)
-  - [Arguments](#arguments)
-  - [Positionals](#positionals)
-  - [Pre-Validation Hook](#pre-validation-hook)
-  - [Help Message](#help-message)
-  - [Zod Utilities](#zod-utilities)
-  - [Type Utilities](#type-utilities)
+  - [Creating a subcommand](#creating-a-subcommand)
+  - [Creating options](#creating-options)
+  - [Creating typed arguments](#creating-typed-arguments)
+  - [Using Schemas](#using-schemas)
+  - [Default Values and Optional Inputs](#default-values-and-optional-inputs)
+  - [Positionals vs Typed Arguments](#positionals-vs-typed-arguments)
+  - [Option and Argument Constraints](#option-and-argument-constraints)
+  - [Negating a boolean option](#negating-a-boolean-option)
+  - [Creating a Custom Help Message Style](#creating-a-custom-help-message-style)
+  - [Help Message as HTML](#help-message-as-html)
 - [API Reference](#api-reference)
-  - [Methods](#methods)
-  - [Types](#types)
-- [Example](#example)
+  - [Type Utilities](#type-utilities)
+  - [Coerce Helpers](#coerce-helpers)
+  - [Markdown Generation](#markdown-generation)
+  - [Autocompletion Script Generation](#autocompletion-script-generation)
+  - [Help Message](#help-message)
+  - [PrintHelpOptions](#printhelpoptions)
+  - [Cli](#cli)
+  - [Subcommand](#subcommand)
+  - [Option](#option)
+  - [Argument](#argument)
+  - [Context Type](#context-type)
 - [License](#license)
 
 ## Features
 
-- **Strict typing for subcommands, options, and arguments**.
-- **Flag coupling support**: e.g., `-rf` to combine `-r` and `-f` flags.
-- **Negative flag support**: e.g., `--no-verbose` to negate `--verbose`.
-- **Flexible option value formatting**: Supports both `--input-dir path` and `--input-dir=path` styles.
-- **Help message generation**: Built-in methods to generate help text for the CLI and each subcommand.
-- **Auto completion**: Generate shell (bash, zsh, powershell) completion scripts for your CLI.
-- **Documentation**: Generate a markdown documentation for your CLI.
+- **Strictly typed & validated**: Fully TypeScript-typed CLI arguments, backed by schema validation.
+- **Flexible option syntax**: Supports both `--option value` and `--option=value`.
+- **Boolean flags**: Handles negation (`--no-verbose`) and short flag coupling (`-rf`).
+- **Typed subcommands**: Define subcommands with their own typed options and arguments.
+- **Automatic help & docs**: Generate user-friendly CLI help messages and Markdown documentation.
+- **Shell autocompletion**: Auto-generate scripts for Bash, Zsh, and PowerShell.
+- **Schema-agnostic**: Works with any validation library supporting [`StandardSchemaV1`](https://github.com/standard-schema/standard-schema) and default/optional primitives.
+- **Cross-platform**: Fully supports Node.js, Bun, Deno, and modern browsers.
 
 ## Installation
 
 > [!IMPORTANT]  
-> `zod` version `3.25.0` or later (including `4.0.0`) is required.
+> A validation library is required that supports [`StandardSchemaV1`](https://github.com/standard-schema/standard-schema) and allows primitive types to be optional or have default values.
 
 ```bash
-npm install zod chalk zod-args-parser
+npm install zod zod-args-parser
 ```
 
 ## Usage
 
+The following example uses `zod` as the validation library, but you can use any library that supports [`StandardSchemaV1`](https://github.com/standard-schema/standard-schema), as long as it allows primitive types to be optional or have default values.
+
 ```ts
 import * as z from "zod";
-import { createCli, createSubcommand, createOptions, safeParse } from "zod-args-parser";
-
-// Share options between schemas.
-const sharedOptions = createOptions([
-  {
-    name: "verbose",
-    description: "Verbose mode",
-    type: z.boolean().optional(),
-  },
-]);
-
-// Create the CLI program schema
-// This will be used when no subcommands are run
-const cliSchema = createCli({
-  cliName: "my-cli",
-  description: "A description for my CLI",
-  example: "example of how to use my cli\nmy-cli --help",
-  options: [
-    {
-      name: "help",
-      aliases: ["h"],
-      type: z.boolean().optional().describe("Show this help message"),
-    },
-    {
-      name: "version",
-      aliases: ["v"],
-      description: "Show version",
-      type: z.boolean().optional(),
-    },
-    ...sharedOptions,
-  ],
-});
+import { defineCLI, coerce } from "zod-args-parser";
 
-// Execute this function when the CLI is run (no subcommands)
-cliSchema.setAction(results => {
-  const { help, version, verbose } = results;
+// Define the CLI program (main command)
+const listyCLI = defineCLI({
+  cliName: "listy",
 
-  if (help) {
-    results.printCliHelp();
-    return;
-  }
+  subcommands: [
+    // ...
+  ],
 
-  if (version) {
-    console.log("v1.0.0");
-    return;
-  }
+  options: {
+    help: {
+      schema: z.boolean().optional(),
+      coerce: coerce.boolean,
+    },
+  },
 
-  if (verbose) {
-    console.log("Verbose mode enabled");
-  }
+  arguments: {
+    // ...
+  },
 });
 
-// Create a subcommand schema
-const helpCommandSchema = createSubcommand({
-  name: "help",
-  placeholder: "<command>",
-  description: "Print help message for command",
-  arguments: [
-    {
-      name: "command",
-      description: "Command to print help for",
-      type: z.enum(["build", "help", "init"]).optional(),
-    },
-  ],
-});
+// When the CLI (main command) is executed
+listyCLI.onExecute(results => {
+  const { help } = results.options;
 
-// Execute this function when the `help` subcommand is run
-helpCommandSchema.setAction(results => {
-  const [command] = results.arguments;
-  if (command) {
-    results.printSubcommandHelp(command);
+  // print help for the CLI
+  if (help && listyCLI.generateCliHelpMessage) {
+    console.log(listyCLI.generateCliHelpMessage());
     return;
   }
 
-  results.printCliHelp();
+  console.error("Please try `listy --help`");
 });
 
-const schemas = [cliSchema, helpCommandSchema /* Add more subcommands */] as const;
-
-const results = safeParse(process.argv.slice(2), ...schemas);
+// Run the CLI and pass in the command line arguments
+const results = listyCLI.run(process.argv.slice(2));
 
-// ! Error
-if (!results.success) {
+// Inspect parsed results
+if (results.error) {
   console.error(results.error.message);
-  console.log("\n`my-cli --help` for more information, or `my-cli help <command>` for command-specific help\n");
-  process.exit(1);
+  console.log("\n`listy --help` for more information");
 }
 ```
 
+## Example
+
+- [Listy CLI Example](https://github.com/alabsi91/zod-args-parser/tree/main/example)
+
 ## Guide
 
-### Subcommands
+### Creating a subcommand
 
-- Subcommands are defined using the `createSubcommand` function, which accepts an object with the type [`Subcommand`](#subcommand).
-- The following properties are optional and used only for **metadata** such as help messages and documentation:
-  - `description`
-  - `usage`
-  - `example`
-  - `placeholder`
-- Do not reuse the same subcommand name within the same CLI. TypeScript will throw a type error if a duplicate exist.
+Subcommands are defined using the `defineSubcommand` function, which accepts a [`Subcommand`](#subcommand) definition object.
 
 ```ts
-import { createSubcommand } from "zod-args-parser";
-
-const subcommand = createSubcommand({
-  name: "subcommand",
-  description: "Description for the subcommand",
-  usage: "my-cli subcommand [options] [arguments]",
-  example: "subcommand --help",
-  placeholder: "[options] [arguments]",
-  allowPositional: false, // default: false
-  options: [
-    /* options */
-  ],
-  arguments: [
-    /* arguments */
-  ],
-});
+import { defineSubcommand, helpMessageStyles } from "zod-args-parser";
 
-// Executed when the subcommand is run after parsing before validation
-subcommand.setPreValidationHook(ctx => {
-  // ...
-});
+import type { InferInputType, InferOutputType } from "zod-args-parser";
 
-// Executed when the subcommand is run
-subcommand.setAction(results => {
-  // ...
-});
-```
+const createListCommand = defineSubcommand({
+  // The name used to call this subcommand from the CLI
+  name: "add",
 
-### Type Zod Schemas
+  // Additional names that can be used to run the same subcommand
+  aliases: ["cl", "create"],
 
-- A schema with `.optional()` or `.default(<value>)` is treated as **optional**; all others are **required**.
-- Descriptions can be added either via the Zod schema’s `describe` method or the `description` property.
+  // When true: positional (untyped) arguments are allowed and parsed as string[]
+  // When typed arguments exist: they are parsed first, and leftover arguments become `positionals`
+  allowPositionals: false,
 
-> [!IMPORTANT]  
->  All values from the terminal are passed as **strings**, so **coercion** is required except for simple booleans types which are inferred automatically.
+  // Extra information used for CLI help output and generated documentation
+  meta: {
+    // Shown in the terminal when displaying the help text for this subcommand
+    // Ignored in Markdown docs
+    usage: "listy add --list <list> --items <items> --tags <tags>",
 
-```ts
-import * as z from "zod";
+    // Shown in terminal help alongside the subcommand name
+    // Also shown in Markdown docs next to the subcommand name
+    placeholder: "<list> <items> <tags>",
 
-// String examples
-z.string(); // required -> string
-z.string().optional(); // optional -> string | undefined
-z.string().default("hello"); // optional -> string
+    // Shown in terminal help if both description and descriptionMarkdown exist
+    // Not preferred in Markdown docs
+    description: "Plain text description shown in terminal help when both formats are provided.",
 
-// Boolean examples (simple booleans are inferred automatically no need to use coerce)
-z.boolean(); // required -> boolean
-z.boolean().optional(); // optional -> boolean | undefined
-z.boolean().default(true); // optional -> boolean
+    // Used as-is in Markdown docs and preferred over `description`
+    // When printed in the terminal, it will be parsed by `marked` and formatted for the terminal output
+    descriptionMarkdown: "**Formatted** for terminal and preferred when generating **Markdown documentation**.",
 
-// Number examples (need coercion because terminal inputs are strings)
-z.number(); // 🚫 invalid: will always throw
-z.coerce.number(); // ✅ converts string input -> number
+    // Displayed at the bottom of terminal help
+    // In Markdown docs, it is output inside a code block
+    example:
+      "listy add --list groceries --items egg,milk,bread --tags food\n" +
+      "listy add --list todos --items clean,cook --tags chores|work",
 
-// String boolean (zod v4) -> boolean
-z.stringbool({
-  truthy: ["true", "1", "yes", "on", "y", "enabled"],
-  falsy: ["false", "0", "no", "off", "n", "disabled"],
-});
+    // If true, this subcommand is hidden from both help output and documentation
+    // Useful for internal commands
+    hidden: false,
+  },
 
-// Enum -> "a" | "b" | "c"
-z.enum(["a", "b", "c"]);
+  // Available CLI options for this subcommand
+  options: {
+    // ...
+  },
 
-// Union -> number | "development"
-z.union([z.coerce.number(), z.literal("development")]);
+  // Typed command-line arguments for this subcommand
+  arguments: {
+    // ...
+  },
+});
 
-// Custom preprocessing:
-import { stringToArray, stringToSet } from "zod-args-parser";
+// Runs when the subcommand is executed
+// Multiple handlers can be attached if needed
+const unsubscribe = createListCommand.onExecute(results => {
+  const { ...options } = results.options;
+  const { ...args } = results.arguments;
+  const positionals = results.positionals;
+
+  // Inspect parsed results in detail
+  console.log(results.context.options);
+
+  // Print help for this subcommand
+  if (createListCommand.generateSubcommandHelpMessage) {
+    console.log(
+      createListCommand.generateSubcommandHelpMessage(results.subcommand, { style: helpMessageStyles.default }),
+    );
+    return;
+  }
 
-// Array -> string[]
-z.preprocess((value: string) => stringToArray(value), z.string().array());
+  // Print help for the CLI
+  if (listyCLI.generateCliHelpMessage) {
+    console.log(listyCLI.generateCliHelpMessage({ style: helpMessageStyles.default }));
+    return;
+  }
+});
 
-// Tuple -> [string, number, boolean]
-z.preprocess(
-  (value: string) => stringToArray(value, ";"), // second arg is the separator (default: ",")
-  z.tuple([z.string(), z.coerce.number(), z.coerce.boolean()]),
-);
+// Programmatic API for executing this subcommand
+export const executeCreateListCommand = createListCommand.execute;
 
-// Set -> Set<string>
-z.preprocess((value: string) => stringToSet(value), z.set(z.string()));
+// Useful inferred types for input/output payloads
+type CreateListInput = InferInputType<typeof createListCommand>;
+type CreateListOutput = InferOutputType<typeof createListCommand>;
 ```
 
-### Options
+### Creating options
 
-- Option names and aliases must use a valid **JavaScript** variable name.
-  - **Supports:** `camelCase`, `PascalCase`, `snake_case`, and `SCREAMING_SNAKE_CASE`.
-  - **Examples:**
-    - `I` or `i` ➡️ `-i`
-    - `InputDir`, `inputDir`, or `INPUT_DIR` ➡️ `--input-dir`
-    - `Help`, `help`, or `HELP` ➡️ `--help`
-- Do not use same options/aliases name with different casing.
-- Do not reuse the option/alias name within the same CLI/subcommand. TypeScript will throw a type error if duplicates exist.
-- The following properties are optional and used only for **metadata** such as help messages and documentation:
-  - `description`
-  - `example`
-  - `placeholder`
+Options can be defined directly inside the CLI or subcommand definition. Or using the `defineOptions` function.
 
-See the [Option](#option) type for more details.
+Option names can use any common case style:
+`camelCase`, `PascalCase`, `snake_case`, or `SCREAMING_SNAKE_CASE`.
+
+- ListName `=>` --list-name
+- list-name `=>` --list-name
+- listName `=>` --list-name
+- LIST_NAME `=>` --list-name
 
 ```ts
-import * as z from "zod";
-import { createCli } from "zod-args-parser";
-
-// Define the CLI schema
-const cliSchema = createCli({
-  cliName: "my-cli",
-  options: [
-    {
-      name: "inputDir", // camelCase option name becomes `--input-dir`
-      aliases: ["i"], // single-letter alias becomes `-i`
-      type: z.boolean().default(false), // optional because of default
-      description: "Input directory",
-      placeholder: "<dir>",
-      example: "-i /path/to/dir",
-    },
-    {
-      name: "verbose", // another option
-      aliases: ["v"], // alias `-v`
-      type: z.boolean().optional().describe("Enable verbose mode"), // using describe() instead of description
-    },
-  ],
-});
+import { defineSubcommand, coerce } from "zod-args-parser";
 
-// Define the CLI action
-cliSchema.setAction(results => {
-  const { inputDir, verbose } = results.options;
+const createListCommand = defineSubcommand({
+  // ...
 
-  // inputDir: boolean (optional, with default = false)
-  // verbose: boolean | undefined (optional, no default)
-});
-```
+  options: {
+    // The key is the option name
+    listName: {
+      // Aliases generate equivalent flags (e.g. -n, --name)
+      aliases: ["list", "name", "n"],
 
-### Arguments
+      // Required string for this option
+      schema: z.string(),
 
-- Arguments are strictly typed **positional values**, defined as a tuple: `[arg1, arg2, arg3]`.
-- Each argument must have a **name**, which is used for help messages and documentation. TypeScript will throw a type error if duplicates name exist within the same CLI/subcommand.
-- The following properties are optional and used only for **metadata**:
-  - `description`
-  - `example`
+      // Converts the raw terminal input into a string.
+      // In this case, because the schema already expects a string, this coercion is redundant
+      coerce: coerce.string,
 
-> [!IMPORTANT]  
->  Arguments are parsed strictly **in order**.
->
-> - Only the **last argument** may be optional (when `allowPositional` is disabled).
-> - Mixing required and optional arguments (e.g., required → optional → required) will cause parsing errors because the parser cannot determine which value belongs to which argument.
-> - This means you **cannot have any optional arguments** if `allowPositional` is enabled.
-> - TypeScript will throw a type error if required and optional arguments are mixed, or when using `allowPositional: true` with optional arguments.
+      // When true: this option cannot appear alongside other options/arguments,
+      // except those listed in `requires`
+      exclusive: false,
 
-See the [Argument](#argument) type for more details.
+      // If this option is used, the listed options/arguments must also be provided
+      requires: [],
 
-```ts
-import * as z from "zod";
-import { createCli } from "zod-args-parser";
-
-// Define the CLI schema
-const cliSchema = createCli({
-  cliName: "my-cli",
-  arguments: [
-    {
-      name: "inputFile", // argument name (camelCase for consistency)
-      type: z.string(), // required
-      description: "Input file",
-      example: "input.txt",
-    },
-    {
-      name: "outputFile", // second argument
-      type: z.string().optional(), // optional (only allowed as the last arg)
-      description: "Output file",
-      example: "output.txt",
-    },
-  ],
-});
+      // Options/arguments that cannot be used together with this one
+      // Avoid using `conflictWith` when `exclusive` is true
+      conflictWith: [],
 
-// Define the CLI action
-cliSchema.setAction(results => {
-  const [inputFile, outputFile] = results.arguments;
+      // Extra metadata used for help output and documentation
+      meta: {
+        // Shown next to the option name in terminal help and Markdown docs
+        placeholder: "<list> <items> <tags>",
 
-  // inputFile: string (required)
-  // outputFile: string | undefined (optional, no default)
-});
-```
+        // Displayed in terminal help if both descriptions exist
+        // Not preferred in Markdown
+        description: "Plain text description shown in terminal help when both formats are provided.",
 
-### Positionals
+        // Preferred in Markdown and kept formatted when printed in terminal output
+        descriptionMarkdown: "**Formatted** for terminal and preferred when generating **Markdown documentation**.",
 
-- Positionals are untyped **positional values**, always parsed as `string[]` of any length.
-- By default, positionals are **not allowed**. Enable them using the `allowPositional` option.
+        // Appears at the end of this option’s description in terminal help
+        // Rendered inside a code block in Markdown
+        example:
+          "listy add --list groceries --items egg,milk,bread --tags food\n" +
+          "listy add --list todos --items clean,cook --tags chores|work",
 
-> [!IMPORTANT]  
->  If both typed arguments and positionals are used in the same CLI/subcommand, the **typed arguments are parsed first**, and only then are the remaining values collected as positionals.
+        // Shows this value as the default in help/docs (does not change runtime default)
+        default: `"default-list"`,
 
-```ts
-import { createSubcommand } from "zod-args-parser";
-
-// Define the subcommand schema
-export const countSchema = createSubcommand({
-  name: "count",
-  aliases: ["list"],
-  description: "Print a list of items provided by the user",
-  allowPositional: true, // enable positionals
-});
+        // Shows this option as optional/required in help/docs (visual override only)
+        optional: false,
 
-// Define the subcommand action
-countSchema.setAction(results => {
-  const items = results.positional; // string[]
+        // When true, hides this option from both help output and docs
+        hidden: false,
+      },
+    },
 
-  if (items.length === 0) {
-    console.log("No items provided");
-    return;
-  }
+    items: {
+      schema: z.string().array(),
+      // Parses comma-separated lists into string[]
+      coerce: coerce.stringArray(","),
+    },
 
-  console.log("-- List of items --\n -", items.join("\n - "));
+    tags: {
+      schema: z.enum(["food", "work", "chores"]).array(),
+      // Parses pipe-separated tags into Set<string>
+      coerce: coerce.stringSet("|"),
+    },
+  },
 });
 ```
 
-### Pre-Validation Hook
+### Creating typed arguments
 
-- The `preValidationHook` is called after parsing but before validation.
-- The provided context object can be modified before validation for advanced use cases.
-- When using **async** hooks, make sure to call [`parseAsync`](#parseasync) or [`safeParseAsync`](#parseasync).
+Arguments can be defined directly inside the CLI or subcommand definition. Or using the `defineArguments` function.
 
-See the [Context](#context) type for more details.
+The order of argument definitions matters.
 
-```ts
-import * as z from "zod";
-import { createCli } from "zod-args-parser";
-
-// Define the CLI schema
-const cliSchema = createCli({
-  cliName: "my-cli",
-  options: [
-    { name: "inputDir", type: z.string() },
-    { name: "verbose", type: z.boolean().default(false) },
-  ],
-  arguments: [
-    { name: "first-argument", type: z.string() },
-    { name: "second-argument", type: z.string().optional() },
-  ],
-});
+**Rules**:
 
-// Define the pre-validation hook
-cliSchema.setPreValidationHook(ctx => {
-  if (ctx.options.verbose.source === "default") {
-    ctx.options.verbose.rawValue = "true";
-  }
+1. If `allowPositionals: true` → typed arguments cannot be optional.
+2. If `allowPositionals: false` → only the last typed argument may be optional.
+3. Argument names cannot be numeric, because it affects argument ordering.
 
-  if (ctx.arguments[0].source === "cli") {
-    console.log("first-argument:", ctx.arguments[0].rawValue);
-  }
-});
-
-// Define the CLI action
-cliSchema.setAction(results => {
-  // can access `ctx` here
-  console.log(results.ctx.options.verbose);
+```ts
+import { defineSubcommand, coerce } from "zod-args-parser";
+
+const createListCommand = defineSubcommand({
+  arguments: {
+    // In help output, argument names are automatically converted to kebab-case by default.
+    argumentName: {
+      // Same fields as options, but arguments do not support aliases
+      schema: z.string(),
+      coerce: coerce.string, // redundant (the input is already a string)
+      exclusive: false,
+      requires: [],
+      conflictWith: [],
+      meta: {
+        // Overrides the displayed argument name in help and documentation
+        name: "argument-name",
+
+        // Other meta fields work the same way as option metadata
+      },
+    },
+  },
 });
 ```
 
-### Help Message
+### Using schemas
 
-Cli help message example preview
+Other validation libraries can be used as long as they support [`StandardSchemaV1`](https://github.com/standard-schema/standard-schema) and allow primitive types to be optional or have default values.
 
-<img width="1153" height="682" alt="image" src="https://github.com/user-attachments/assets/5610e5d0-8c08-4776-bbfc-b8e655241c39" /><br>
+Here are some examples:
 
-Subcommand help message example preview
+| Vendor   | `string?`                | `string="value"`                  | coerce          |
+| -------- | ------------------------ | --------------------------------- | --------------- |
+| Zod      | `z.string().optional()`  | `z.string().default("value")`     | `coerce.string` |
+| Valibot  | `v.optional(v.string())` | `v.optional(v.string(), "value")` | `coerce.string` |
+| Decoders | `d.optional(v.string())` | `d.optional(v.string(), "value")` | `coerce.string` |
+| Sury     | `S.optional(v.string())` | `S.optional(v.string(), "value")` | `coerce.string` |
 
-<img width="1115" height="522" alt="image" src="https://github.com/user-attachments/assets/2a56a549-4059-45c4-84d2-93adaedaaac8" /><br>
+| Vendor   | `string[]?`                       | `string[]=["value"]`                         | coerce                    |
+| -------- | --------------------------------- | -------------------------------------------- | ------------------------- |
+| Zod      | `z.array(z.string()).optional()`  | `z.array(z.string()).default(["value"])`     | `coerce.stringArray(",")` |
+| Valibot  | `v.optional(v.array(v.string()))` | `v.optional(v.array(v.string()), ["value"])` | `coerce.stringArray(",")` |
+| Decoders | `d.optional(d.array(d.string))`   | `d.optional(d.array(d.string), ["value"])`   | `coerce.stringArray(",")` |
+| Sury     | `S.optional(S.array(S.string))`   | `S.optional(S.array(S.string), ["value"])`   | `coerce.stringArray(",")` |
 
-There are two ways to print the help message:
+### Default Values and Optional Inputs
 
-1. `printCliHelp(style?: HelpMessageStyle)`  
-   Print the help message for the CLI.
+- Optional values and defaults for **options and typed arguments** are controlled by the schema used for validation.
+- `meta.optional` and `meta.default` only affect help/documentation output; they do **not** affect runtime behavior.
+- The CLI parser enforces types and applies defaults according to the schema.
+- Example schemas:
+  - `z.string().optional()` → optional input
+  - `z.string().default("value")` → input with default value
 
-2. `printSubcommandHelp(subcommandName: string, style?: HelpMessageStyle)`  
-   Print the help message for a specific subcommand.
-
-See the [HelpMessageStyle](#helpmsgstyle) type for more details.
-
-```ts
-import chalk from "chalk";
-import { formatCliHelpMsg, formatSubcommandHelpMsg, helpMessageStyles } from "zod-args-parser";
+### Positionals vs Typed Arguments
 
-// Define the CLI schema
-const cliSchema = createCli(/* ... */);
+Think of typed arguments as **reserved seats** at the front of the line, and positionals as **everyone standing behind them**.
 
-// Define the subcommand schema
-const subcommandSchema = createSubcommand(/* ... */);
+- Typed arguments are filled **in order from left to right**.
+- Any remaining inputs become positionals **only if `allowPositionals: true`**.
 
-subcommandSchema.setAction(results => {
-  // print help for CLI (without colors)
-  results.printCliHelp(helpMessageStyles.noColors);
+#### Rules
 
-  // choose a style
-  results.printCliHelp(helpMessageStyles.dracula);
+| Setting                   | Behavior                                                                                                                       |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `allowPositionals: true`  | Typed arguments are parsed first. Remaining inputs go into `positionals`. Typed arguments **cannot** be optional in this mode. |
+| `allowPositionals: false` | All inputs must match typed arguments. Only the **last** typed argument may be optional. Extra inputs cause an error.          |
 
-  // print help for subcommand (with custom title color)
-  results.printSubcommandHelp("build", { title: chalk.red });
-});
+### Option and Argument Constraints
 
-const schemas = [cliSchema, subcommandSchema] as const;
+Both options and typed arguments support rules to control valid combinations:
 
-// print help functions also accessible here
-const results = safeParse(args, ...schemas);
-if (results.success) {
-  results.printCliHelp();
-}
+#### `exclusive: boolean`
 
-// get the string without printing to console
-const cliHelp = formatCliHelpMsg(schemas, helpMessageStyles.html);
-console.log(`<pre style="background-color: #1e1e2e">${cliHelp}</pre>`);
+- Cannot be used together with other options or arguments, except those explicitly listed in `requires`.
 
-const subcommandHelp = formatSubcommandHelpMsg(subcommandSchema, helpMessageStyles.html, cliSchema.cliName);
-console.log(`<pre style="background-color: #1e1e2e">${subcommandHelp}</pre>`);
-```
+#### `requires: string[]`
 
-### Zod Utilities
+- Lists other options/arguments names (not aliases) that **must be provided** if this one is used.
+- Helps enforce dependencies between flags or arguments.
 
-- `isOptionalSchema(schema: ZodTypeAny): boolean`  
-  Check if a schema is optional or has a default value.
+#### `conflictWith: string[]`
 
-- `schemaDefaultValue(schema: ZodTypeAny): unknown | undefined`  
-  Get the default value of a schema if it has one.
+- Lists other options/arguments names (not aliases) that **cannot be used together** with this one.
+- Prevents incompatible combinations and avoids ambiguous behavior.
 
-- `stringToArray(value: string, separator?: string = ","): string[]`  
-  A preprocessing handle to convert a string to an array.
+### Negating a boolean option
 
-- `stringToSet(value: string, separator?: string = ","): Set<string>`  
-  A preprocessing handle to convert a string to a set.
+Boolean options can be negated by prefixing them with `no-` or by using the equals sign `=`.
 
-```ts
-import * as z from "zod";
-import { createCli, isOptionalSchema, schemaDefaultValue, stringToArray } from "zod-args-parser";
-
-const cliSchema = createCli({
-  cliName: "my-cli",
-  options: [
-    {
-      name: "tags",
-      aliases: ["t"],
-      placeholder: "<list>",
-      description: "tags separated by semicolon (;)",
-      example: "--tags tag1;tag2;tag3",
-      type: z.preprocess((value: string) => stringToArray(value, ";"), z.array(z.string())),
-    },
-    {
-      name: "verbose",
-      aliases: ["v"],
-      description: "Verbose mode",
-      type: z.boolean().default(false),
-    },
-  ],
-});
+```sh
+--bool        true
+--no-bool     false
 
-cliSchema.setAction(results => {
-  const ctxOptions = results.ctx.options;
+--bool=true   true
+--bool=false  false
 
-  console.log(
-    isOptionalSchema(ctxOptions.verbose.schema), // true
-    schemaDefaultValue(ctxOptions.verbose.schema), // false
-  );
-});
+-v            true
+--no-v        false
 ```
 
-### Type Utilities
-
-- `InferOptionsInput<Cli | Subcommand>`  
-  Infer the options input type (before zod validation) from the Cli or subcommand schema.
-
-- `InferOptionsOutput<Cli | Subcommand>`  
-  Infer the options Output type (after zod validation) from the Cli or subcommand schema.
+### Creating a Custom Help Message Style
 
-- `InferArgumentsInput<Cli | Subcommand>`  
-  Infer the arguments input type (before zod validation) from the Cli or subcommand schema.
-
-- `InferArgumentsOutput<Cli | Subcommand>`  
-  Infer the arguments Output type (after zod validation) from the Cli or subcommand schema.
+You can define a custom style for CLI help messages by implementing the `HelpMessageStyle` interface. A common approach is to start from an existing style and override only the parts you want.
 
 ```ts
-import { createSubcommand } from "zod-args-parser";
-import type { InferOptionsOutput, InferArgumentsOutput } from "zod-args-parser";
-
-const subcommand = createSubcommand({
-  name: "subcommand",
-  options: [
-    { name: "numberOption", type: z.coerce.number() },
-    { name: "stringOption", type: z.string() },
-    { name: "booleanOption", type: z.boolean() },
-    { name: "optionalOption", type: z.boolean().optional() },
-  ],
-  arguments: [
-    { name: "stringArgument", type: z.string() },
-    { name: "numberArgument", type: z.coerce.number() },
-    { name: "booleanArgument", type: z.boolean() },
-  ],
-});
+import chalk from "chalk";
+import { HelpMessageStyle, helpMessageStyles } from "zod-args-parser";
 
-type Options = InferOptionsOutput<typeof subcommand>;
-// { numberOption: number; stringOption: string; booleanOption: boolean; optionalOption?: boolean | undefined; }
+// Example: create a new style based on the default style
+const myCustomStyle = new HelpMessageStyle(
+  {
+    title: chalk.bold.magenta,
+    option: chalk.yellow,
+    argument: chalk.green,
+  },
+  // optionally use default style as base
+  helpMessageStyles.default,
+);
 
-type Arguments = InferArgumentsOutput<typeof subcommand>;
-// [string, number, boolean]
+// Use the custom style when generating help
+console.log(myCli.generateCliHelpMessage({ style: myCustomStyle }));
 ```
 
-## API Reference
-
-### Methods
-
-#### createCli
+### Help Message as HTML
 
-`(schema: Cli) => Cli & SetMethods<Cli>`
+You can generate the CLI help message as HTML using the `html` style and insert it into a `<pre>` element.
 
-Creates the CLI program schema.
-
-See [Cli](#cli) object type.
+```ts
+import { listyCLI, helpMessageStyles, generateCliHelpMessage } from "zod-args-parser";
 
-#### createSubcommand
+// Generate help message as HTML string
+const htmlHelp = generateCliHelpMessage(listyCLI, { style: helpMessageStyles.html, markdownRenderer: "html" });
 
-`(schema: Subcommand) => Subcommand & SetMethods<Subcommand>`
+// Insert into a <pre> element in your page
+const pre = document.createElement("pre");
+pre.innerHTML = htmlHelp;
+document.body.appendChild(pre);
+```
 
-Creates the subcommand schema.
+You can style Markdown content using CSS:
 
-See [Subcommand](#subcommand) object type.
+```css
+span._markdown * {
+  white-space: initial;
+}
+```
 
-#### createOptions
+## API Reference
 
-`(schema: Option[]) => Option[]`
+### Type Utilities
 
-Creates an array of option schemas for option sharing.
+#### `InferInputType<T extends Cli | Subcommand>`
 
-See [Option](#option) object type.
+Infer options, arguments, and positionals input types from the CLI/subcommand definition.
 
-#### createArguments
+#### `InferOutputType<T extends Cli | Subcommand>`
 
-`(schema: Argument[]) => Argument[]`
+Infer options, arguments, and positionals output types from the CLI/subcommand definition.
 
-Creates an array of argument schemas for argument sharing.
+#### `InferOptionsInputType<T extends Cli | Subcommand>`
 
-See [Argument](#argument) object type.
+Infer options input type from the CLI/subcommand definition.
 
-#### parse
+#### `InferOptionsOutputType<T extends Cli | Subcommand>`
 
-`(args: string[], cli: Cli, ...subcommands: Subcommand[]) => Result`
+Infer options output type from the CLI/subcommand definition.
 
-Parses and validates the provided arguments and throws an error if parsing or validation failed.
+#### `InferArgumentsInputType<T extends Cli | Subcommand>`
 
-See [Cli](#cli), [Subcommand](#subcommand), and [Results](#results)
+Infer arguments input type from the CLI/subcommand definition.
 
-#### parseAsync
+#### `InferArgumentsOutputType<T extends Cli | Subcommand>`
 
-`(args: string[], cli: Cli, ...subcommands: Subcommand[]) => Promise<Result>`
+Infer arguments output type from the CLI/subcommand definition.
 
-Same as [`parse`](#parse), but returns a promise.  
-Use this when you have async actions or hooks.
+```ts
+import type { defineSubcommand, InferInputType, InferOutputType } from "zod-args-parser";
 
-See [Cli](#cli), [Subcommand](#subcommand), and [Results](#results)
+const subcommand = defineSubcommand({
+  // ...
+});
 
-#### safeParse
+type InputType = InferInputType<typeof subcommand>;
+type OutputType = InferOutputType<typeof subcommand>;
+```
 
-`(args: string[], cli: Cli, ...subcommands: Subcommand[]) => { success: false, error: Error } | { success: true, data: Result }`
+### Coerce Helpers
 
-Parses and validates the provided arguments without throwing an error.
+- `coerce.string`
+- `coerce.number`
+- `coerce.boolean`
+- `coerce.stringArray(separator: string)`
+- `coerce.numberArray(separator: string)`
+- `coerce.booleanArray(separator: string)`
+- `coerce.stringSet(separator: string)`
+- `coerce.numberSet(separator: string)`
+- `coerce.booleanSet(separator: string)`
+- `coerce.json<T>()`
 
-See [Cli](#cli), [Subcommand](#subcommand), and [Results](#results)
+### Markdown Generation
 
-#### safeParseAsync
+#### generateMarkdown
 
-`(args: string[], cli: Cli, ...subcommands: Subcommand[]) => Promise<...>`
+`(cliDefinition: Cli) => string`
 
-Same as [`safeParse`](#safeparse), but returns a promise.  
-Use this when you have async actions or hooks.
+Generate markdown documentation for a **CLI definition** and return it as a `string`.
 
-See [Cli](#cli), [Subcommand](#subcommand), and [Results](#results)
+### Autocomplete Script Generation
 
 #### generateBashAutocompleteScript
 
-`(...params: [Cli, ...Subcommand[]]) => string`
-
-Generates an autocomplete script for `bash`.
-
-See [Cli](#cli) and [Subcommand](#subcommand)
+`(cliDefinition: Cli) => string`
 
-#### generatePowerShellAutocompleteScript
-
-`(...params: [Cli, ...Subcommand[]]) => string`
-
-Generates an autocomplete script for `powershell`.
-
-See [Cli](#cli) and [Subcommand](#subcommand)
+Generate a Bash autocomplete script for a **CLI definition** and return it as a `string`.
 
 #### generateZshAutocompleteScript
 
-`(...params: [Cli, ...Subcommand[]]) => string`
-
-Generates an autocomplete script for `zsh`.
-
-See [Cli](#cli) and [Subcommand](#subcommand)
-
-#### generateMarkdown
-
-`(...params: [Cli, ...Subcommand[]]) => string`
-
-Generates a markdown documentation for your CLI.
+`(cliDefinition: Cli) => string`
 
-See [Cli](#cli) and [Subcommand](#subcommand)
+Generate a zsh autocomplete script for a **CLI definition** and return it as a `string`.
 
-### Types
-
-#### Cli
-
-| Name            | Type                       | Description                                    | Example                        |
-| --------------- | -------------------------- | ---------------------------------------------- | ------------------------------ |
-| cliName         | `string`                   | The name of the CLI program.                   | `"my-cli"`                     |
-| description     | `string?`                  | A description of the CLI for the help message. | `"Build the project"`          |
-| usage           | `string?`                  | The usage of the CLI for the help message.     | `"my-cli build"`               |
-| example         | `string?`                  | An example of CLI usage for the help message.  | `"my-cli <command> [options]"` |
-| options         | [`Option[]?`](#option)     | An array of options for the CLI.               |                                |
-| arguments       | [`Argument[]?`](#argument) | An array of arguments for the CLI.             |                                |
-| allowPositional | `boolean?`                 | Allows positional arguments for the CLI.       |                                |
-
-#### Subcommand
-
-| Name            | Type                       | Description                                           | Example                    |
-| --------------- | -------------------------- | ----------------------------------------------------- | -------------------------- |
-| name            | `string`                   | The name of the subcommand.                           | `"build"`                  |
-| aliases         | `string[]?`                | An array of aliases for the subcommand.               | `["b", "build"]`           |
-| description     | `string?`                  | A description of the subcommand for the help message. | `"Build the project"`      |
-| usage           | `string?`                  | The usage of the subcommand for the help message.     | `"my-cli build"`           |
-| placeholder     | `string?`                  | A placeholder displayed in the help message.          | `"[options]"`              |
-| example         | `string?`                  | An example of subcommand usage for the help message.  | `"my-cli build [options]"` |
-| options         | [`Option[]?`](#option)     | An array of options for the subcommand.               |                            |
-| arguments       | [`Argument[]?`](#argument) | An array of arguments for the subcommand.             |                            |
-| allowPositional | `boolean?`                 | Allows positional arguments for this subcommand.      |                            |
+#### generatePowerShellAutocompleteScript
 
-#### Option
+`(cliDefinition: Cli) => string`
 
-| Name        | Type        | Description                                          | Example                         |
-| ----------- | ----------- | ---------------------------------------------------- | ------------------------------- |
-| name        | `string`    | The name of the option. camelCase is recommended.    | `"inputDir"` -> `--input-dir`   |
-| type        | `ZodType`   | Specifies the type of the option using Zod schema.   | `z.boolean().default(false)`    |
-| aliases     | `string[]?` | An array of aliases for the option.                  | `["i", "dir"]` -> `-i`, `--dir` |
-| description | `string?`   | A description of the option for the help message.    | `"Input directory"`             |
-| placeholder | `string?`   | Placeholder text for the option in the help message. | `"<dir>"` or `"<path>"`         |
-| example     | `string?`   | An example of option usage for the help message.     | `"-i /path/to/dir"`             |
+Generate a PowerShell autocomplete script for a **CLI definition** and return it as a `string`.
 
-#### Argument
+### Help Message
 
-| Name        | Type      | Description                                          | Example                             |
-| ----------- | --------- | ---------------------------------------------------- | ----------------------------------- |
-| name        | `string`  | The name of the argument for the help message.       | `"command-name"`                    |
-| type        | `ZodType` | Specifies the type of the argument using Zod schema. | `z.enum(["build", "help", "init"])` |
-| description | `string?` | A description of the argument for the help message.  | `"Command to print help for"`       |
-| example     | `string?` | An example of argument usage for the help message.   | `"help build"`                      |
+#### generateCliHelpMessage
+
+`(cliDefinition: Cli, printOptions?: PrintHelpOptions) => string`
+
+Generate a help message for a **CLI definition** and return it as a `string`.  
+See [`PrintHelpOptions`](#printhelpoptions) and [`Cli`](#cli).
+
+#### generateSubcommandHelpMessage
+
+`(commandDefinition: Subcommand, options?: PrintHelpOptions, cliName?: string) => string`
+
+Generate a help message for a **subcommand definition** and return it as a `string`.  
+See [`PrintHelpOptions`](#printhelpoptions) and [`Subcommand`](#subcommand).
+
+#### printCliHelp
+
+`(cliDefinition: Cli, options?: PrintHelpOptions) => void`
+
+Print a help message for a **CLI definition**.  
+See [`PrintHelpOptions`](#printhelpoptions) and [`Cli`](#cli).
+
+#### printSubcommandHelp
+
+`(commandDefinition: Subcommand, options?: PrintHelpOptions, cliName?: string) => void`
+
+Print a help message for a **subcommand definition**.  
+See [`PrintHelpOptions`](#printhelpoptions) and [`Subcommand`](#subcommand).
+
+### PrintHelpOptions
+
+| Option                  | Type                   | Default                     | Description                                                                         |
+| ----------------------- | ---------------------- | --------------------------- | ----------------------------------------------------------------------------------- |
+| style                   | `HelpMessageStyle`     | `helpMessageStyles.default` | The style to use for the help message.                                              |
+| kebabCaseArgumentName   | `boolean`              | `true`                      | Whether to transform the argument (not option) name to kebab case.                  |
+| markdownRenderer        | `"terminal" \| "html"` | `"terminal"`                | The renderer to use for the markdown.                                               |
+| indentBeforeName        | `number`               | `2`                         | The number of spaces before the name of option/argument/subcommand.                 |
+| indentAfterName         | `number`               | `4`                         | Spaces after the name, between the name and description (space between columns).    |
+| indentBeforePlaceholder | `number`               | `1`                         | The number of spaces to put before the placeholder.                                 |
+| newLineIndent           | `number`               | `0`                         | Spaces before a new line for description or example under description.              |
+| emptyLines              | `number`               | `0`                         | Number of empty lines between lines.                                                |
+| emptyLinesBeforeTitle   | `number`               | `1`                         | Number of empty lines before the title.                                             |
+| emptyLinesAfterTitle    | `number`               | `0`                         | Number of empty lines after the title.                                              |
+| exampleKeyword          | `string`               | `"Example:"`                | The keyword to use for examples.                                                    |
+| optionalKeyword         | `string`               | `"(optional)"`              | The keyword to use for optional values.                                             |
+| defaultKeyword          | `string`               | `"(default: {{ value }})"`  | The keyword to indicate default values, with `{{ value }}` replaced by the default. |
+| usageTitle              | `string`               | `"USAGE"`                   | The title to use for the usage section.                                             |
+| descriptionTitle        | `string`               | `"DESCRIPTION"`             | The title to use for the description section.                                       |
+| commandsTitle           | `string`               | `"COMMANDS"`                | The title to use for the commands section.                                          |
+| optionsTitle            | `string`               | `"OPTIONS"`                 | The title to use for the options section.                                           |
+| argumentsTitle          | `string`               | `"ARGUMENTS"`               | The title to use for the arguments section.                                         |
+| exampleTitle            | `string`               | `"EXAMPLE"`                 | The title to use for the examples section.                                          |
+
+### Cli
+
+| Property            | Type                       | Description                                                                                                                                                                                          |
+| ------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cliName`           | `string`                   | The name of the CLI program (main command).                                                                                                                                                          |
+| `subcommands?`      | `Subcommand[]`             | Array of subcommands. Do not manually construct subcommand objects; always create them via `defineSubcommand()` and pass the returned object. See [`Subcommand Definition`](#subcommand-definition). |
+| `allowPositionals?` | `boolean`                  | When `true`, enables positional arguments for the CLI; positionals are untyped `string[]`. If typed `arguments` are present, they are parsed first and any remaining args become `positionals`.      |
+| `options?`          | `Record<string, Option>`   | A dictionary of option definitions keyed by a valid JavaScript variable name (e.g., `inputDir` → `--input-dir`). See [`Option Definition`](#option-definition).                                      |
+| `arguments?`        | `Record<string, Argument>` | Strictly ordered typed arguments. See [`Argument Definition`](#argument-definition).                                                                                                                 |
+| `meta?`             | `CliMeta`                  | Metadata for the CLI used for help messages and documentation generation.                                                                                                                            |
+
+### CliMeta
+
+| Property               | Type     | Description                                                                                                                     |
+| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `usage?`               | `string` | Usage string example (e.g., `cliName subcommand [options] <arg1> <arg2>`).                                                      |
+| `description?`         | `string` | Short explanation. Supports multi-line text and ANSI colors. Preferred for terminal output when present.                        |
+| `descriptionMarkdown?` | `string` | Markdown-formatted description used for generated documentation and terminal markdown. Used for Markdown generation if present. |
+| `example?`             | `string` | Examples shown to the user (displayed as a code block in Markdown).                                                             |
+
+### Subcommand
+
+| Property            | Type                       | Description                                                                                                                                                                                             |
+| ------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`              | `string`                   | The subcommand name. Must be unique within a CLI across names and aliases.                                                                                                                              |
+| `aliases?`          | `string[]`                 | A list of aliases that can be used to invoke this subcommand. Must not collide with other names or aliases in the same CLI.                                                                             |
+| `allowPositionals?` | `boolean`                  | When `true`, enables positional arguments for this subcommand. Positionals are untyped `string[]`. If typed `arguments` are present, they are parsed first and any remaining args become `positionals`. |
+| `options?`          | `Record<string, Option>`   | A dictionary of option definitions keyed by a valid JavaScript variable name (e.g., `inputDir` → `--input-dir`). See [`Option Definition`](#option-definition).                                         |
+| `arguments?`        | `Record<string, Argument>` | Strictly ordered, typed arguments (the order matters). [`Argument Definition`](#argument-definition).                                                                                                   |
+| `meta?`             | `SubcommandMeta`           | Metadata used for help messages and documentation generation. Inlined in the table below.                                                                                                               |
+
+### SubcommandMeta
+
+| Property               | Type      | Description                                                                                                                                                                                                 |
+| ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `placeholder?`         | `string`  | Text displayed after the subcommand name to show expected arguments (e.g., `<list> <items>`).                                                                                                               |
+| `usage?`               | `string`  | Usage string example (e.g. `cliName subcommand [options] <arg1> <arg2>`).                                                                                                                                   |
+| `description?`         | `string`  | Short explanation. Supports multi-line text and ANSI color styles. Preferred for terminal output if both `description` and `descriptionMarkdown` are provided.                                              |
+| `descriptionMarkdown?` | `string`  | Markdown-formatted description used for generated documentation and terminal markdown. If both `description` and `descriptionMarkdown` are provided, `descriptionMarkdown` is used for Markdown generation. |
+| `example?`             | `string`  | Examples shown to the user (displayed inside a code block in markdown).                                                                                                                                     |
+| `hidden?`              | `boolean` | When `true`, hide this item from documentation/help output. Useful for internal or undocumented commands/options.                                                                                           |
+
+### Option
+
+| Property        | Type                | Description                                                                                                                          |
+| --------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `aliases?`      | `string[]`          | A list of short alias keys (JavaScript variable names) that map to short CLI flags (e.g., `i` → `-i`).                               |
+| `schema`        | `Schema`            | A schema to validate the user input. (e.g., Zod: `z.string().optional()`).                                                           |
+| `coerce?`       | `CoerceMethod<...>` | Coercion function used to convert `string` input to the schema's output type. Not required when the expected input type is `string`. |
+| `exclusive?`    | `boolean`           | When `true`, this option must appear on its own (except for entries listed in `requires`).                                           |
+| `requires?`     | `string[]`          | Names of other options/arguments that must be explicitly provided when this option is used.                                          |
+| `conflictWith?` | `string[]`          | Names of other options/arguments that conflict with this option.                                                                     |
+| `meta?`         | `OptionMeta`        | Metadata used for help messages and documentation generation. Inlined in the table below.                                            |
+
+### OptionMeta
+
+| Property       | Type      | Description                                                                                    |
+| -------------- | --------- | ---------------------------------------------------------------------------------------------- |
+| `placeholder?` | `string`  | Text to display as a placeholder for the expected value (e.g., `<path>`).                      |
+| `default?`     | `string`  | Custom default value shown in docs/help. Use an empty string to intentionally show no default. |
+| `optional?`    | `boolean` | Override whether this option is considered optional in the generated help documentation.       |
+
+### Argument
+
+| Property        | Type                | Description                                                                                                                          |
+| --------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `schema`        | `Schema`            | Schema to validate the user input.                                                                                                   |
+| `coerce?`       | `CoerceMethod<...>` | Coercion function used to convert `string` input to the schema's output type. Not required when the expected input type is `string`. |
+| `exclusive?`    | `boolean`           | When `true`, this argument must appear on its own (except for items listed in `requires`).                                           |
+| `requires?`     | `string[]`          | Names of other options/arguments that must be explicitly provided when this argument is used.                                        |
+| `conflictWith?` | `string[]`          | Names of other options/arguments that conflict with this argument.                                                                   |
+| `meta?`         | `ArgumentMeta`      | Metadata used for help messages and documentation generation. Inlined in the table below.                                            |
+
+### ArgumentMeta
+
+| Property    | Type      | Description                                                                                    |
+| ----------- | --------- | ---------------------------------------------------------------------------------------------- |
+| `name?`     | `string`  | Override the argument name in the help message and documentation.                              |
+| `default?`  | `string`  | Custom default value shown in help/docs. Use an empty string to intentionally show no default. |
+| `optional?` | `boolean` | Override whether this argument is considered optional in the generated help documentation.     |
+
+### Context Type
+
+Represents detailed information about how each option or argument was provided (terminal, default, or programmatic).  
+Useful for inspecting where values came from and what raw input was used.
 
 #### Context
 
-The context object is generated after parsing the CLI arguments and before validation.
-
-| Name       | Type                                     | Description                                                                                              |
-| ---------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| subcommand | `string \| undefined`                    | The name of the executed subcommand.                                                                     |
-| options    | `{ [OptionName: string]: ParsedOption }` | A map of parsed options for the CLI/subcommand.                                                          |
-| arguments  | `ParsedArgument[] \| undefined`          | An array of parsed arguments for the CLI/subcommand. See [`ParsedArgument`](#parsedargument)             |
-| positional | `string[] \| undefined`                  | Contains positional arguments when `allowPositional` is enabled. See [`ParsedArgument`](#parsedargument) |
-
-##### ParsedOption
-
-| Name     | Type                  | Description                                                                                    |
-| -------- | --------------------- | ---------------------------------------------------------------------------------------------- |
-| name     | `string`              | The name of the option (e.g. `foo` or `f`).                                                    |
-| flag     | `string \| undefined` | The CLI flag as provided in the terminal (e.g. `--foo` or `-f`).                               |
-| schema   | `ZodTypeAny`          | The schema that validates this option.                                                         |
-| rawValue | `string \| undefined` | The string value as provided in the terminal. boolean flags are inferred into boolean strings. |
-| source   | `"cli" \| "default"`  | `cli`: provided explicitly in the CLI, `default`: not provided, and the schema has a default.  |
-
-##### ParsedArgument
-
-| Name     | Type                  | Description                                                                                   |
-| -------- | --------------------- | --------------------------------------------------------------------------------------------- |
-| schema   | `ZodTypeAny`          | The schema that validates this argument.                                                      |
-| rawValue | `string \| undefined` | The raw string value supplied for this argument from the CLI.                                 |
-| source   | `"cli" \| "default"`  | `cli`: provided explicitly in the CLI, `default`: not provided, and the schema has a default. |
-
-#### Results
-
-| Name                   | Type                                                 | Description                                                                           |
-| ---------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| subcommand             | `string \| undefined`                                | The name of the executed subcommand.                                                  |
-| `[optionName: string]` | `unknown`                                            | Validated options for the CLI/subcommand.                                             |
-| arguments              | `unknown[] \| undefined`                             | Validated arguments for the CLI/subcommand.                                           |
-| positional             | `string[] \| undefined`                              | Positional array for the CLI/subcommand.                                              |
-| printCliHelp           | `(style?: HelpMessageStyle) => void`                     | Prints the CLI help message. See [HelpMessageStyle](#helpmsgstyle)                        |
-| printSubcommandHelp    | `(subcommand: string, style?: HelpMessageStyle) => void` | Prints the help message for a specified subcommand. See [HelpMessageStyle](#helpmsgstyle) |
-
-#### HelpMessageStyle
-
-Available styles: `default`, `dracula`, `solarizedDark`, `nord`, `html`, `gruvboxDark`, `monokai`, `oneDark`, `noColors`
-
-Each style has the following properties:
-
-| Key          | Type                             | Default                |
-| ------------ | -------------------------------- | ---------------------- |
-| title        | `(...text: unknown[]) => string` | `chalk.bold.blue`      |
-| description  | `(...text: unknown[]) => string` | `chalk.white`          |
-| default      | `(...text: unknown[]) => string` | `chalk.dim.italic`     |
-| optional     | `(...text: unknown[]) => string` | `chalk.dim.italic`     |
-| exampleTitle | `(...text: unknown[]) => string` | `chalk.yellow`         |
-| example      | `(...text: unknown[]) => string` | `chalk.dim`            |
-| command      | `(...text: unknown[]) => string` | `chalk.yellow`         |
-| option       | `(...text: unknown[]) => string` | `chalk.cyan`           |
-| argument     | `(...text: unknown[]) => string` | `chalk.green`          |
-| placeholder  | `(...text: unknown[]) => string` | `chalk.hex("#FF9800")` |
-| punctuation  | `(...text: unknown[]) => string` | `chalk.white.dim`      |
-
-## Example
-
-- [Example code](https://github.com/alabsi91/zod-args-parser/tree/main/example)
+| Field         | Type                              | Description                                       |
+| ------------- | --------------------------------- | ------------------------------------------------- |
+| `subcommand`  | `string` \| `undefined`           | Name of the executed subcommand, if any.          |
+| `options`     | `Record<string, OptionContext>`   | Per-option context, with source and raw values.   |
+| `arguments`   | `Record<string, ArgumentContext>` | Per-argument context, with source and raw values. |
+| `positionals` | `string[]` \| `never`             | Raw positional arguments when allowed.            |
+
+#### OptionContext
+
+| Property       | Description                                                                          |
+| -------------- | ------------------------------------------------------------------------------------ |
+| `schema`       | Schema used to validate the option.                                                  |
+| `optional`     | Whether the option schema is optional.                                               |
+| `defaultValue` | Default value from the schema, if any.                                               |
+| `flag`         | CLI flag used (e.g., `--foo`, `-f`) when source is `terminal`.                       |
+| `stringValue`  | Raw string provided from CLI when source is `terminal`.                              |
+| `passedValue`  | Value passed programmatically when source is `programmatic`.                         |
+| `source`       | `"terminal"`, `"default"`, or `"programmatic"` indicates how the value was supplied. |
+
+#### ArgumentContext
+
+| Property       | Description                                                                          |
+| -------------- | ------------------------------------------------------------------------------------ |
+| `schema`       | Schema used to validate the argument.                                                |
+| `optional`     | Whether the argument schema is optional.                                             |
+| `defaultValue` | Default value from the schema, if any.                                               |
+| `stringValue`  | Raw string from CLI when source is `terminal`.                                       |
+| `passedValue`  | Value passed programmatically when source is `programmatic`.                         |
+| `source`       | `"terminal"`, `"default"`, or `"programmatic"` indicates how the value was supplied. |
 
 ## License