洪 民憙 (Hong Minhee) 
@hongminhee@hollo.social
Optique 0.7.0 released!
- “Did you mean?” typo suggestions
- Zod & Valibot schema validation
- Duplicate option detection
- Context-aware error messages
Type-safe CLI parsing for TypeScript just got friendlier.
洪 民憙 (Hong Minhee)
@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
// --versionThe 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()andextractArgumentMetavars()to the@optique/core/usagemodule 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/runFor 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/bunLooking 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!
