Stop writing if statements for your CLI flags

If you've built CLI tools, you've written code like this: if (opts.reporter === "junit" && !opts.outputFile) { throw new Error("--output-file is required for junit reporter");}if (opts.reporter === "html" && !opts.outputFile) { throw new Error("--output-file is required for html reporter");}if (opts.reporter === "console" && opts.outputFile) { console.warn("--output-file is ignored for console reporter");} A few months ago, I wrote Stop writing CLI validation. Parse it right the first time. about parsing individual option values correctly. But it didn't cover the relationships between options. In the code above, --output-file only makes sense when --reporter is junit or html. When it's console, the option shouldn't exist at all. We're using TypeScript. We have a powerful type system. And yet, here we are, writing runtime checks that the compiler can't help with. Every time we add a new reporter type, we need to remember to update these checks. Every time we refactor, we hope we didn't miss one. The state of TypeScript CLI parsers The old guard—Commander, yargs, minimist—were built before TypeScript became mainstream. They give you bags of strings and leave type safety as an exercise for the reader. But we've made progress. Modern TypeScript-first libraries like cmd-ts and Clipanion (the library powering Yarn Berry) take types seriously: // cmd-tsconst app = command({ args: { reporter: option({ type: string, long: 'reporter' }), outputFile: option({ type: string, long: 'output-file' }), }, handler: (args) => { // args.reporter: string // args.outputFile: string },});// Clipanionclass TestCommand extends Command { reporter = Option.String('--reporter'); outputFile = Option.String('--output-file');} These libraries infer types for individual options. --port is a number. --verbose is a boolean. That's real progress. But here's what they can't do: express that --output-file is required when --reporter is junit, and forbidden when --reporter is console. The relationship between options isn't captured in the type system. So you end up writing validation code anyway: handler: (args) => { // Both cmd-ts and Clipanion need this if (args.reporter === "junit" && !args.outputFile) { throw new Error("--output-file required for junit"); } // args.outputFile is still string | undefined // TypeScript doesn't know it's definitely string when reporter is "junit"} Rust's clap and Python's Click have requires and conflicts_with attributes, but those are runtime checks too. They don't change the result type. If the parser configuration knows about option relationships, why doesn't that knowledge show up in the result type? Modeling relationships with conditional() Optique treats option relationships as a first-class concept. Here's the test reporter scenario: import { conditional, object } from "@optique/core/constructs";import { option } from "@optique/core/primitives";import { choice, string } from "@optique/core/valueparser";import { run } from "@optique/run";const parser = conditional( option("--reporter", choice(["console", "junit", "html"])), { console: object({}), junit: object({ outputFile: option("--output-file", string()), }), html: object({ outputFile: option("--output-file", string()), openBrowser: option("--open-browser"), }), });const [reporter, config] = run(parser); The conditional() combinator takes a discriminator option (--reporter) and a map of branches. Each branch defines what other options are valid for that discriminator value. TypeScript infers the result type automatically: type Result = | ["console", {}] | ["junit", { outputFile: string }] | ["html", { outputFile: string; openBrowser: boolean }]; When reporter is "junit", outputFile is string—not string | undefined. The relationship is encoded in the type. Now your business logic gets real type safety: const [reporter, config] = run(parser);switch (reporter) { case "console": runWithConsoleOutput(); break; case "junit": // TypeScript knows config.outputFile is string writeJUnitReport(config.outputFile); break; case "html": // TypeScript knows config.outputFile and config.openBrowser exist writeHtmlReport(config.outputFile); if (config.openBrowser) openInBrowser(config.outputFile); break;} No validation code. No runtime checks. If you add a new reporter type and forget to handle it in the switch, the compiler tells you. A more complex example: database connections Test reporters are a nice example, but let's try something with more variation. Database connection strings: myapp --db=sqlite --file=./data.dbmyapp --db=postgres --host=localhost --port=5432 --user=adminmyapp --db=mysql --host=localhost --port=3306 --user=root --ssl Each database type needs completely different options: SQLite just needs a file path PostgreSQL needs host, port, user, and optionally password MySQL needs host, port, user, and has an SSL flag Here's how you model this: import { conditional, object } from "@optique/core/constructs";import { withDefault, optional } from "@optique/core/modifiers";import { option } from "@optique/core/primitives";import { choice, string, integer } from "@optique/core/valueparser";const dbParser = conditional( option("--db", choice(["sqlite", "postgres", "mysql"])), { sqlite: object({ file: option("--file", string()), }), postgres: object({ host: option("--host", string()), port: withDefault(option("--port", integer()), 5432), user: option("--user", string()), password: optional(option("--password", string())), }), mysql: object({ host: option("--host", string()), port: withDefault(option("--port", integer()), 3306), user: option("--user", string()), ssl: option("--ssl"), }), }); The inferred type: type DbConfig = | ["sqlite", { file: string }] | ["postgres", { host: string; port: number; user: string; password?: string }] | ["mysql", { host: string; port: number; user: string; ssl: boolean }]; Notice the details: PostgreSQL defaults to port 5432, MySQL to 3306. PostgreSQL has an optional password, MySQL has an SSL flag. Each database type has exactly the options it needs—no more, no less. With this structure, writing dbConfig.ssl when the mode is sqlite isn't a runtime error—it's a compile-time impossibility. Try expressing this with requires_if attributes. You can't. The relationships are too rich. The pattern is everywhere Once you see it, you find this pattern in many CLI tools: Authentication modes: const authParser = conditional( option("--auth", choice(["none", "basic", "token", "oauth"])), { none: object({}), basic: object({ username: option("--username", string()), password: option("--password", string()), }), token: object({ token: option("--token", string()), }), oauth: object({ clientId: option("--client-id", string()), clientSecret: option("--client-secret", string()), tokenUrl: option("--token-url", url()), }), }); Deployment targets, output formats, connection protocols—anywhere you have a mode selector that determines what other options are valid. Why conditional() exists Optique already has an or() combinator for mutually exclusive alternatives. Why do we need conditional()? The or() combinator distinguishes branches based on structure—which options are present. It works well for subcommands like git commit vs git push, where the arguments differ completely. But in the reporter example, the structure is identical: every branch has a --reporter flag. The difference lies in the flag's value, not its presence. // This won't work as intendedconst parser = or( object({ reporter: option("--reporter", choice(["console"])) }), object({ reporter: option("--reporter", choice(["junit", "html"])), outputFile: option("--output-file", string()) }),); When you pass --reporter junit, or() tries to pick a branch based on what options are present. Both branches have --reporter, so it can't distinguish them structurally. conditional() solves this by reading the discriminator's value first, then selecting the appropriate branch. It bridges the gap between structural parsing and value-based decisions. The structure is the constraint Instead of parsing options into a loose type and then validating relationships, define a parser whose structure is the constraint. Traditional approachOptique approachParse → Validate → UseParse (with constraints) → UseTypes and validation logic maintained separatelyTypes reflect the constraintsMismatches found at runtimeMismatches found at compile time The parser definition becomes the single source of truth. Add a new reporter type? The parser definition changes, the inferred type changes, and the compiler shows you everywhere that needs updating. Try it If this resonates with a CLI you're building: Documentation Tutorial conditional() reference GitHub Next time you're about to write an if statement checking option relationships, ask: could the parser express this constraint instead? The structure of your parser is the constraint. You might not need that validation code at all.

CLIのオプション分岐、もうif文は書かなくていい

Optique 0.8.0: Conditional parsing, pass-through options, and LogTape integration

We're excited to announce Optique 0.8.0! This release introduces powerful new features for building sophisticated CLI applications: the conditional() combinator for discriminated union patterns, the passThrough() parser for wrapper tools, and the new @optique/logtape package for seamless logging configuration. Optique is a type-safe combinatorial CLI parser for TypeScript, providing a functional approach to building command-line interfaces with composable parsers and full type inference. New conditional parsing with conditional() Ever needed to enable different sets of options based on a discriminator value? The new conditional() combinator makes this pattern first-class. It creates discriminated unions where certain options only become valid when a specific discriminator value is selected. import { conditional, object } from "@optique/core/constructs";import { option } from "@optique/core/primitives";import { choice, string } from "@optique/core/valueparser";const parser = conditional( option("--reporter", choice(["console", "junit", "html"])), { console: object({}), junit: object({ outputFile: option("--output-file", string()) }), html: object({ outputFile: option("--output-file", string()) }), });// Result type: ["console", {}] | ["junit", { outputFile: string }] | ... Key features: Explicit discriminator option determines which branch is selected Tuple result [discriminator, branchValue] for clear type narrowing Optional default branch for when discriminator is not provided Clear error messages indicating which options are required for each discriminator value The conditional() parser provides a more structured alternative to or() for discriminated union patterns. Use it when you have an explicit discriminator option that determines which set of options is valid. See the conditional() documentation for more details and examples. Pass-through options with passThrough() Building wrapper CLI tools that need to forward unrecognized options to an underlying tool? The new passThrough() parser enables legitimate wrapper/proxy patterns by capturing unknown options without validation errors. import { object } from "@optique/core/constructs";import { option, passThrough } from "@optique/core/primitives";const parser = object({ debug: option("--debug"), extra: passThrough(),});// mycli --debug --foo=bar --baz=qux// → { debug: true, extra: ["--foo=bar", "--baz=qux"] } Key features: Three capture formats: "equalsOnly" (default, safest), "nextToken" (captures --opt val pairs), and "greedy" (captures all remaining tokens) Lowest priority (−10) ensures explicit parsers always match first Respects -- options terminator in "equalsOnly" and "nextToken" modes Works seamlessly with object(), subcommands, and other combinators This feature is designed for building Docker-like CLIs, build tool wrappers, or any tool that proxies commands to another process. See the passThrough() documentation for usage patterns and best practices. LogTape logging integration The new @optique/logtape package provides seamless integration with LogTape, enabling you to configure logging through command-line arguments with various parsing strategies. # Denodeno add --jsr @optique/logtape @logtape/logtape# npmnpm add @optique/logtape @logtape/logtape Quick start with the loggingOptions() preset: import { loggingOptions, createLoggingConfig } from "@optique/logtape";import { object } from "@optique/core/constructs";import { parse } from "@optique/core/parser";import { configure } from "@logtape/logtape";const parser = object({ logging: loggingOptions({ level: "verbosity" }),});const args = ["-vv", "--log-output=-"];const result = parse(parser, args);if (result.success) { const config = await createLoggingConfig(result.value.logging); await configure(config);} The package offers multiple approaches to control log verbosity: verbosity() parser: The classic -v/-vv/-vvv pattern where each flag increases verbosity (no flags → "warning", -v → "info", -vv → "debug", -vvv → "trace") debug() parser: Simple --debug/-d flag that toggles between normal and debug levels logLevel() value parser: Explicit --log-level=debug option for direct level selection logOutput() parser: Log output destination with - for console or file path for file output See the LogTape integration documentation for complete examples and configuration options. Bug fix: negative integers now accepted Fixed an issue where the integer() value parser rejected negative integers when using type: "number". The regex pattern has been updated from /^\d+$/ to /^-?\d+$/ to correctly handle values like -42. Note that type: "bigint" already accepted negative integers, so this change brings consistency between the two types. Installation # Denodeno add jsr:@optique/core# npmnpm add @optique/core# pnpmpnpm add @optique/core# Yarnyarn add @optique/core# Bunbun add @optique/core For the LogTape integration: # Denodeno add --jsr @optique/logtape @logtape/logtape# npmnpm add @optique/logtape @logtape/logtape# pnpmpnpm add @optique/logtape @logtape/logtape# Yarnyarn add @optique/logtape @logtape/logtape# Bunbun add @optique/logtape @logtape/logtape Looking forward Optique 0.8.0 continues our focus on making CLI development more expressive and type-safe. The conditional() combinator brings discriminated union patterns to the forefront, passThrough() enables new wrapper tool use cases, and the LogTape integration makes logging configuration a breeze. As always, all new features maintain full backward compatibility—your existing parsers continue to work unchanged. We're grateful to the community for feedback and suggestions. If you have ideas for future improvements or encounter any issues, please let us know through GitHub Issues. For more information about Optique and its features, visit the documentation or check out the full changelog.

Optique 0.7.0: Smarter error messages and validation library integrations

Optique 0.7.0 introduces enhancements focused on improving the developer experience and expanding its ecosystem for type-safe CLI argument parsing in TypeScript. This release brings automatic "Did you mean?" suggestions to help users correct typos, along with seamless integrations for Zod and Valibot validation libraries, ensuring more robust and efficient CLI development. Duplicate option name detection is now included to catch configuration bugs early, and context-aware error messages provide users with precise feedback. The update also features customizable shell completion naming conventions and improved line break handling in error messages. With these new features, Optique aims to streamline CLI development in TypeScript, making it more intuitive and less error-prone. This release underscores Optique's commitment to providing developers with powerful tools for building high-quality CLI applications.

feature or docs request: "extra options" parser · Issue #35 · dahlia/optique

First of all, thank you for this excellent project. I'm still getting familiar with it, but it's been a fun time so far. I'm writing a wrapper around another tool. The wrapper has some extra option...

Optique 0.6.0: Shell completion support for type-safe CLI parsers

Optique 0.6.0 introduces intelligent shell completion to type-safe command-line applications, supporting Bash, zsh, fish, PowerShell, and Nushell. Unlike traditional CLI frameworks, Optique leverages the same parser structure for both argument parsing and completion, eliminating duplicate definitions and ensuring synchronization. Setting up completion is straightforward, with users generating and sourcing a completion script for their shell. The system works automatically with all Optique parser types, offering context-aware suggestions, including file system completion and custom logic for domain-specific value parsers. Additionally, the release enhances command documentation with separate brief, description, and footer texts, and introduces a `commandLine()` message term for clearer command-line examples in help text. Existing Optique users can easily migrate by adding a `completion` option to their `run()` configuration. This release aims to make Optique-based CLIs more user-friendly without sacrificing type safety and composability, providing sophisticated runtime features while maintaining compile-time guarantees.

Optique 0.5.0: Enhanced error handling and message customization

Optique 0.5.0 is now available, bringing enhancements to error handling, help text generation, and overall developer experience while maintaining full backward compatibility. The update introduces better code organization by refactoring the large `@optique/core/parser` module into three focused modules: `@optique/core/primitives`, `@optique/core/modifiers`, and `@optique/core/constructs`. Error handling is improved with automatic conversion of default value callback errors into parser-level errors, and the new `WithDefaultError` class allows for structured error messages. Customization of default values in help text is now possible via an optional third parameter to `withDefault()`, enabling descriptive text instead of actual values. Additionally, the release provides comprehensive error message customization across all parser types and combinators, allowing context-specific feedback. These improvements aim to make Optique more user-friendly, especially for building CLI applications that require clear error messages and helpful documentation, making this release a significant step forward for developers using Optique.