Optique 0.7.0: Smarter error messages and validation library integrations

[hongminhee@hackers.pub]

We're thrilled to announce Optique 0.7.0, a release focused on developer experience improvements and expanding Optique's ecosystem with validation library integrations.

Optique is a type-safe, combinatorial CLI argument parser for TypeScript. Unlike traditional CLI libraries that rely on configuration objects, Optique lets you compose parsers from small, reusable functions—bringing the same functional composition patterns that make Zod powerful to CLI development. If you're new to Optique, check out Why Optique? to learn how this approach unlocks possibilities that configuration-based libraries simply can't match.

This release introduces automatic “Did you mean?” suggestions for typos, seamless integration with Zod and Valibot validation libraries, duplicate option name detection for catching configuration bugs early, and context-aware error messages that help users understand exactly what went wrong.

“Did you mean?”: Automatic typo suggestions

We've all been there: you type --verbos instead of --verbose, and the CLI responds with an unhelpful “unknown option” error. Optique 0.7.0 changes this by automatically suggesting similar options when users make typos:

const parser = object({
  verbose: option("-v", "--verbose"),
  version: option("--version"),
});

// User types: --verbos (typo)
const result = parse(parser, ["--verbos"]);
// Error: Unexpected option or argument: --verbos.
//
// Did you mean one of these?
//   --verbose
//   --version

The suggestion system uses Levenshtein distance to find similar names, suggesting up to 3 alternatives when the edit distance is within a reasonable threshold. Suggestions work automatically for both option names and subcommand names across all parser types—option(), flag(), command(), object(), or(), and longestMatch(). See the automatic suggestions documentation for more details.

Customizing suggestions

You can customize how suggestions are formatted or disable them entirely through the errors option:

// Custom suggestion format for option/flag parsers
const portOption = option("--port", integer(), {
  errors: {
    noMatch: (invalidOption, suggestions) =>
      suggestions.length > 0
        ? message`Unknown option ${invalidOption}. Try: ${values(suggestions)}`
        : message`Unknown option ${invalidOption}.`
  }
});

// Custom suggestion format for combinators
const config = object({
  host: option("--host", string()),
  port: option("--port", integer())
}, {
  errors: {
    suggestions: (suggestions) =>
      suggestions.length > 0
        ? message`Available options: ${values(suggestions)}`
        : []
  }
});

Zod and Valibot integrations

Two new packages join the Optique family, bringing powerful validation capabilities from the TypeScript ecosystem to your CLI parsers.

@optique/zod

The new @optique/zod package lets you use Zod schemas directly as value parsers:

import { option, object } from "@optique/core";
import { zod } from "@optique/zod";
import { z } from "zod";

const parser = object({
  email: option("--email", zod(z.string().email())),
  port: option("--port", zod(z.coerce.number().int().min(1).max(65535))),
  format: option("--format", zod(z.enum(["json", "yaml", "xml"]))),
});

The package supports both Zod v3.25.0+ and v4.0.0+, with automatic error formatting that integrates seamlessly with Optique's message system. See the Zod integration guide for complete usage examples.

@optique/valibot

For those who prefer a lighter bundle, @optique/valibot integrates with Valibot—a validation library with a significantly smaller footprint (~10KB vs Zod's ~52KB):

import { option, object } from "@optique/core";
import { valibot } from "@optique/valibot";
import * as v from "valibot";

const parser = object({
  email: option("--email", valibot(v.pipe(v.string(), v.email()))),
  port: option("--port", valibot(v.pipe(
    v.string(),
    v.transform(Number),
    v.integer(),
    v.minValue(1),
    v.maxValue(65535)
  ))),
});

Both packages support custom error messages through their respective error handler options (zodError and valibotError), giving you full control over how validation failures are presented to users. See the Valibot integration guide for complete usage examples.

Duplicate option name detection

A common source of bugs in CLI applications is accidentally using the same option name in multiple places. Previously, this would silently cause ambiguous parsing where the first matching parser consumed the option.

Optique 0.7.0 now validates option names at parse time and fails with a clear error message when duplicates are detected:

const parser = object({
  input: option("-i", "--input", string()),
  interactive: option("-i", "--interactive"),  // Oops! -i is already used
});

// Error: Duplicate option name -i found in fields: input, interactive.
// Each option name must be unique within a parser combinator.

This validation applies to object(), tuple(), merge(), and group() combinators. The or() combinator continues to allow duplicate option names since its branches are mutually exclusive. See the duplicate detection documentation for more details.

If you have a legitimate use case for duplicate option names, you can opt out with allowDuplicates: true:

const parser = object({
  input: option("-i", "--input", string()),
  interactive: option("-i", "--interactive"),
}, { allowDuplicates: true });

Context-aware error messages

Error messages from combinators are now smarter about what they report. Instead of generic "No matching option or command found" messages, Optique now analyzes what the parser expects and provides specific feedback:

// When only arguments are expected
const parser1 = or(argument(string()), argument(integer()));
// Error: Missing required argument.

// When only commands are expected
const parser2 = or(command("add", addParser), command("remove", removeParser));
// Error: No matching command found.

// When both options and arguments are expected
const parser3 = object({
  port: option("--port", integer()),
  file: argument(string()),
});
// Error: No matching option or argument found.

Dynamic error messages with NoMatchContext

For applications that need internationalization or context-specific messaging, the errors.noMatch option now accepts a function that receives a NoMatchContext object:

const parser = or(
  command("add", addParser),
  command("remove", removeParser),
  {
    errors: {
      noMatch: ({ hasOptions, hasCommands, hasArguments }) => {
        if (hasCommands && !hasOptions && !hasArguments) {
          return message`일치하는 명령을 찾을 수 없습니다.`;  // Korean
        }
        return message`잘못된 입력입니다.`;
      }
    }
  }
);

Shell completion naming conventions

The run() function now supports configuring whether shell completions use singular or plural naming conventions:

run(parser, {
  completion: {
    name: "plural",  // Uses "completions" and "--completions"
  }
});

// Or for singular only
run(parser, {
  completion: {
    name: "singular",  // Uses "completion" and "--completion"
  }
});

The default "both" accepts either form, maintaining backward compatibility while letting you enforce a consistent style in your CLI.

Additional improvements

• Line break handling: formatMessage() now distinguishes between soft breaks (single \n, converted to spaces) and hard breaks (double \n\n, creating paragraph separations), improving multi-line error message formatting.

• New utility functions: Added extractOptionNames() and extractArgumentMetavars() to the @optique/core/usage module for programmatic access to parser metadata.

Installation

deno add --jsr @optique/core @optique/run
npm  add       @optique/core @optique/run
pnpm add       @optique/core @optique/run
yarn add       @optique/core @optique/run
bun  add       @optique/core @optique/run

For validation library integrations:

# Zod integration
deno add jsr:@optique/zod     # Deno
npm  add     @optique/zod      # npm/pnpm/yarn/bun

# Valibot integration
deno add jsr:@optique/valibot  # Deno
npm  add     @optique/valibot  # npm/pnpm/yarn/bun

Looking forward

This release represents our commitment to making CLI development in TypeScript as smooth as possible. The “Did you mean?” suggestions and validation library integrations were among the most requested features, and we're excited to see how they improve your CLI applications.

For detailed documentation and examples, visit the Optique documentation. We welcome your feedback and contributions on GitHub!