Optique 0.7.0: Smarter error messages and validation library integrations
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!
