Piero Bosio Social Web Site Personale

When I started building Fedify, an ActivityPub server framework, I ran into a problem that surprised me: I couldn't figure out how to add logging.

Not because logging is hard—there are dozens of mature logging libraries for JavaScript. The problem was that they're primarily designed for applications, not for libraries that want to stay unobtrusive.

I wrote about this a few months ago, and the response was modest—some interest, some skepticism, and quite a bit of debate about whether the post was AI-generated. I'll be honest: English isn't my first language, so I use LLMs to polish my writing. But the ideas and technical content are mine.

Several readers wanted to see a real-world example rather than theory.

The problem: existing loggers assume you're building an app

Fedify helps developers build federated social applications using the ActivityPub protocol. If you've ever worked with federation, you know debugging can be painful. When an activity fails to deliver, you need to answer questions like:

• Did the HTTP request actually go out?
• Was the signature generated correctly?
• Did the remote server reject it? Why?
• Was there a problem parsing the response?

These questions span multiple subsystems: HTTP handling, cryptographic signatures, JSON-LD processing, queue management, and more. Without good logging, debugging turns into guesswork.

But here's the dilemma I faced as a library author: if I add verbose logging to help with debugging, I risk annoying users who don't want their console cluttered with Fedify's internal chatter. If I stay silent, users struggle to diagnose issues.

I looked at the existing options. With winston or Pino, I would have to either:

• Configure a logger inside Fedify (imposing my choices on users), or
• Ask users to pass a logger instance to Fedify (adding boilerplate)

There's also debug, which is designed for this use case. But it doesn't give you structured, level-based logs that ops teams expect—and it relies on environment variables, which some runtimes like Deno restrict by default for security reasons.

None of these felt right. So I built LogTape—a logging library designed from the ground up for library authors. And Fedify became its first real user.

The solution: hierarchical categories with zero default output

The key insight was simple: a library should be able to log without producing any output unless the application developer explicitly enables it.

Fedify uses LogTape's hierarchical category system to give users fine-grained control over what they see. Here's how the categories are organized:

…and about a dozen more. Each category corresponds to a distinct subsystem.

This means a user can configure logging like this:

await configure({
  sinks: { console: getConsoleSink() },
  loggers: [
    // Show errors from all of Fedify
    { category: "fedify", sinks: ["console"], lowestLevel: "error" },
    // But show debug info for inbox processing specifically
    { category: ["fedify", "federation", "inbox"], sinks: ["console"], lowestLevel: "debug" },
  ],
});

When something goes wrong with incoming activities, they get detailed logs for that subsystem while keeping everything else quiet. No code changes required—just configuration.

Request tracing with implicit contexts

The hierarchical categories solved the filtering problem, but there was another challenge: correlating logs across async boundaries.

In a federated system, a single user action might trigger a cascade of operations: fetch a remote actor, verify their signature, process the activity, fan out to followers, and so on. When something fails, you need to correlate all the log entries for that specific request.

Fedify uses LogTape's implicit context feature to automatically tag every log entry with a requestId:

await configure({
  sinks: {
    file: getFileSink("fedify.jsonl", { formatter: jsonLinesFormatter })
  },
  loggers: [
    { category: "fedify", sinks: ["file"], lowestLevel: "info" },
  ],
  contextLocalStorage: new AsyncLocalStorage(),  // Enables implicit contexts
});

With this configuration, every log entry automatically includes a requestId property. When you need to debug a specific request, you can filter your logs:

jq 'select(.properties.requestId == "abc-123")' fedify.jsonl

And you'll see every log entry from that request—across all subsystems, all in order. No manual correlation needed.

The requestId is derived from standard headers when available (X-Request-Id, Traceparent, etc.), so it integrates naturally with existing observability infrastructure.

What users actually see

So what does all this configuration actually mean for someone using Fedify?

If a Fedify user doesn't configure LogTape at all, they see nothing. No warnings about missing configuration, no default output, and minimal performance overhead—the logging calls are essentially no-ops.

For basic visibility, they can enable error-level logging for all of Fedify with three lines of configuration. When debugging a specific issue, they can enable debug-level logging for just the relevant subsystem.

And if they're running in production with serious observability requirements, they can pipe structured JSON logs to their monitoring system with request correlation built in.

The same library code supports all these scenarios—whether the user is running on Node.js, Deno, Bun, or edge functions, without extra polyfills or shims. The user decides what they need.

Lessons learned

Building Fedify with LogTape taught me a few things:

Design your categories early. The hierarchical structure should reflect how users will actually want to filter logs. I organized Fedify's categories around subsystems that users might need to debug independently.

Use structured logging. Properties like requestId, activityId, and actorId are far more useful than string interpolation when you need to analyze logs programmatically.

Implicit contexts turned out to be more useful than I expected. Being able to correlate logs across async boundaries without passing context manually made debugging distributed operations much easier. When a user reports that activity delivery failed, I can give them a single jq command to extract everything relevant.

Trust your users. Some library authors worry about exposing too much internal detail through logs. I've found the opposite—users appreciate being able to see what's happening when they need to. The key is making it opt-in.

Try it yourself

If you're building a library and struggling with the logging question—how much to log, how to give users control, how to avoid being noisy—I'd encourage you to look at how Fedify does it.

The Fedify logging documentation explains everything in detail. And if you want to understand the philosophy behind LogTape's design, my earlier post covers that.

LogTape isn't trying to replace winston or Pino for application developers who are happy with those tools. It fills a different gap: logging for libraries that want to stay out of the way until users need them. If that's what you're looking for, it might be a better fit than the usual app-centric loggers.

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-ts
const app = command({
  args: {
    reporter: option({ type: string, long: 'reporter' }),
    outputFile: option({ type: string, long: 'output-file' }),
  },
  handler: (args) => {
    // args.reporter: string
    // args.outputFile: string
  },
});

// Clipanion
class 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.db
myapp --db=postgres --host=localhost --port=5432 --user=admin
myapp --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 intended
const 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.

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.

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.

# Deno
deno add --jsr @optique/logtape @logtape/logtape

# npm
npm 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

# Deno
deno add jsr:@optique/core

# npm
npm add @optique/core

# pnpm
pnpm add @optique/core

# Yarn
yarn add @optique/core

# Bun
bun add @optique/core

For the LogTape integration:

# Deno
deno add --jsr @optique/logtape @logtape/logtape

# npm
npm add @optique/logtape @logtape/logtape

# pnpm
pnpm add @optique/logtape @logtape/logtape

# Yarn
yarn add @optique/logtape @logtape/logtape

# Bun
bun 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.

내일은 liftIO 2025에서 발표… 떨린다…

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!

フェディバースのアドベントカレンダー、去年も参加したんだ。今年も参加しなきゃ！

このように複雑で厄介なJSON-LDの仕様を一つ一つ考慮しながらActivityPubソフトウェアを開発することに疲れたなら、Fedifyを使ってみてください。Fedifyは内部的に（JSON-LDを単なるJSONとして扱う実装ではなく）本格的なJSON-LDプロセッサを使用すると同時に、ハイレベルAPIではそれらをすべて抽象化し、JSON-LDを理解していなくてもActivityPubの開発を可能にします。

Optique 0.6.0 is here, bringing intelligent shell completion to your type-safe
command-line applications. This release introduces built-in completion support
for Bash, zsh, fish, PowerShell, and Nushell, making your CLIs more
discoverable and user-friendly—all without sacrificing type safety or requiring
duplicate definitions.

For those new to [Optique]: it's a TypeScript CLI parser library that takes
a fundamentally different approach from traditional configuration-based parsers.
Instead of describing your CLI with configuration objects, you compose parsers
from small, type-safe functions. TypeScript automatically infers the exact
types of your parsed data, ensuring compile-time safety while the parser
structure itself provides runtime validation. Think of it as bringing the
composability of parser combinators (inspired by Haskell's
optparse-applicative) together with the type safety of TypeScript's type
system.

Shell completion that just works

The standout feature of this release is comprehensive shell completion support.
Unlike many CLI frameworks that require separate completion definitions,
Optique's completion system leverages the same parser structure used for
argument parsing. This means your completion suggestions automatically stay
synchronized with your CLI's actual behavior—no duplicate definitions, no
manual maintenance.

import { object } from "@optique/core/constructs";
import { argument, option } from "@optique/core/primitives";
import { string, choice } from "@optique/core/valueparser";
import { run } from "@optique/run";

const parser = object({
  format: option("-f", "--format", choice(["json", "yaml", "xml"])),
  output: option("-o", "--output", string({ metavar: "FILE" })),
  verbose: option("-v", "--verbose"),
  input: argument(string({ metavar: "INPUT" })),
});

// Enable completion with a single option
const config = run(parser, { completion: "both" });

Users can now press Tab to get intelligent suggestions:

myapp <TAB>                    # Shows available commands and options
myapp --format <TAB>           # Shows: json, yaml, xml
myapp --format=<TAB>           # Same suggestions with equals syntax
myapp -<TAB>                  # Shows: -f, -o, -v, and other short options

Setting up completion is straightforward. Users generate a completion script
for their shell and source it:

# Bash
myapp completion bash > ~/.bashrc.d/myapp.bash
source ~/.bashrc.d/myapp.bash

# zsh
myapp completion zsh > ~/.zsh/completions/_myapp

# fish
myapp completion fish > ~/.config/fish/completions/myapp.fish

# PowerShell
myapp completion pwsh > myapp-completion.ps1
. ./myapp-completion.ps1

# Nushell
myapp completion nu | save myapp-completion.nu
source myapp-completion.nu

The completion system works automatically with all Optique parser types. When
you use choice() value parsers, the available options become completion
suggestions. When you use path() parsers, file system completion kicks in
with proper handling of extensions and file types. Subcommands, options, and
arguments all provide context-aware suggestions.

What makes Optique's completion special is that it leverages the same parser
structure used for argument parsing. Every parser has an optional suggest()
method that provides context-aware suggestions based on the current input.
Parser combinators like object() and or() automatically aggregate
suggestions from their constituent parsers, ensuring your completion logic
stays in your TypeScript code where it benefits from type safety and testing.

Optique handles the differences between shells transparently. Bash uses the
complete command with proper handling of word splitting, zsh leverages its
powerful compdef system with completion descriptions, fish provides
tab-separated format with automatic file type detection, PowerShell uses
Register-ArgumentCompleter with AST-based parsing, and Nushell integrates
with its external completer system. For file and directory completions, Optique
delegates to each shell's native file completion system, ensuring proper
handling of spaces, symlinks, and platform-specific path conventions.

Custom completion suggestions

For domain-specific value parsers, you can implement custom completion logic
that provides intelligent suggestions based on your application's needs:

import type { ValueParser, ValueParserResult } from "@optique/core/valueparser";
import type { Suggestion } from "@optique/core/parser";
import { message } from "@optique/core/message";

function httpMethod(): ValueParser<string> {
  const methods = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"];

  return {
    metavar: "METHOD",
    parse(input: string): ValueParserResult<string> {
      const method = input.toUpperCase();
      if (methods.includes(method)) {
        return { success: true, value: method };
      }
      return {
        success: false,
        error: message`Invalid HTTP method: ${input}. Valid methods: ${methods.join(", ")}.`,
      };
    },
    format(value: string): string {
      return value;
    },
    *suggest(prefix: string): Iterable<Suggestion> {
      for (const method of methods) {
        if (method.toLowerCase().startsWith(prefix.toLowerCase())) {
          yield {
            kind: "literal",
            text: method,
            description: message`HTTP ${method} request method`
          };
        }
      }
    },
  };
}

The built-in value parsers also provide intelligent suggestions. For instance,
the locale() parser suggests common locale identifiers, the url() parser
offers protocol completions when configured with allowedProtocols, and the
timezone parsers from @optique/temporal use Intl.supportedValuesOf() for
dynamic timezone suggestions.

Enhanced command documentation

This release also introduces new documentation capabilities for the command()
parser. You can now provide separate brief and description texts, along
with a footer for examples and additional information:

import { command, object, constant } from "@optique/core/primitives";
import { message } from "@optique/core/message";

const deployCommand = command(
  "deploy",
  object({
    action: constant("deploy"),
    // ... options
  }),
  {
    brief: message`Deploy application to production`,  // Shown in command list
    description: message`Deploy the application to the production environment.
    
This command handles database migrations, asset compilation, and cache warming
automatically. It performs health checks before switching traffic to ensure
zero-downtime deployment.`,  // Shown in detailed help
    footer: message`Examples:
  myapp deploy --environment staging --dry-run
  myapp deploy --environment production --force

For deployment documentation, see: https://docs.example.com/deploy`
  }
);

The brief text appears when listing commands (like myapp help), while
description provides detailed information when viewing command-specific help
(myapp deploy --help or myapp help deploy). The footer appears at the
bottom of the help text, perfect for examples and additional resources.

Command-line example formatting

To make help text and examples clearer, we've added a new commandLine()
message term type. This displays command-line snippets with distinct cyan
coloring in terminals, making it immediately clear what users should type:

import { message, commandLine } from "@optique/core/message";
import { run } from "@optique/run";

const config = run(parser, {
  footer: message`Examples:
  ${commandLine("myapp --format json input.txt")}
  ${commandLine("myapp --format=yaml --output result.yml data.txt")}
  
To enable shell completion:
  ${commandLine("myapp completion bash > ~/.bashrc.d/myapp.bash")}
  ${commandLine("source ~/.bashrc.d/myapp.bash")}`,
  
  completion: "both"
});

These command examples stand out visually in help text, making it easier for
users to understand how to use your CLI.

Migration guide

If you're already using Optique, adding completion support is straightforward:

1. Update to Optique 0.6.0
2. Add the completion option to your run() configuration:

// Before
const config = run(parser, { help: "both" });

// After
const config = run(parser, { 
  help: "both",
  completion: "both"  // Adds both 'completion' command and '--completion' option
});

That's it! Your CLI now supports shell completion. The completion option
accepts three modes:

• "command": Only the completion subcommand (e.g., myapp completion bash)
• "option": Only the --completion option (e.g., myapp --completion bash)
• "both": Both patterns work

For custom value parsers, you can optionally add a suggest() method to
provide domain-specific completions. Existing parsers continue to work without
modification—they just won't provide custom suggestions beyond what the parser
structure implies.

Looking forward

Shell completion has been one of the most requested features for Optique, and
we're thrilled to deliver it in a way that maintains our core principles: type
safety, composability, and zero duplication. Your parser definitions remain
the single source of truth for both parsing and completion behavior.

This release represents a significant step toward making Optique-based CLIs as
user-friendly as they are developer-friendly. The completion system proves that
we can provide sophisticated runtime features without sacrificing the
compile-time guarantees that make Optique unique.

We hope you find the new shell completion feature useful and look forward to
seeing what you build with it!

Getting started

To start using Optique 0.6.0:

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

For complete documentation, visit optique.dev. Check out the new
shell completion guide for detailed setup instructions and advanced usage
patterns.

For bug reports and feature requests, please visit our GitHub repository.

If you're curious about the context, check out this post by Nur Ketene on LinkedIn and this photo of Vercel CEO Guillermo Rauch with Netanyahu on his X.

We're pleased to announce the release of Optique 0.5.0, which brings significant improvements to error handling, help text generation, and overall developer experience. This release maintains full backward compatibility, so you can upgrade without modifying existing code.

Better code organization through module separation

The large @optique/core/parser module has been refactored into three focused modules that better reflect their purposes. Primitive parsers like option() and argument() now live in @optique/core/primitives, modifier functions such as optional() and withDefault() have moved to @optique/core/modifiers, and combinator functions including object() and or() are now in @optique/core/constructs.

// Before: everything from one module
import { 
  option, flag, argument,        // primitives
  optional, withDefault, multiple, // modifiers
  object, or, merge              // constructs
} from "@optique/core/parser";

// After: organized imports (recommended)
import { option, flag, argument } from "@optique/core/primitives";
import { optional, withDefault, multiple } from "@optique/core/modifiers";
import { object, or, merge } from "@optique/core/constructs";

While we recommend importing from these specialized modules for better clarity, all functions continue to be re-exported from the original @optique/core/parser module to ensure your existing code works unchanged. This reorganization makes the codebase more maintainable and helps developers understand the relationships between different parser types.

Smarter error handling with automatic conversion

One of the most requested features has been better error handling for default value callbacks in withDefault(). Previously, if your callback threw an error—say, when an environment variable wasn't set—that error would bubble up as a runtime exception. Starting with 0.5.0, these errors are automatically caught and converted to parser-level errors, providing consistent error formatting and proper exit codes.

// Before (0.4.x): runtime exception that crashes the app
const parser = object({
  apiUrl: withDefault(option("--url", url()), () => {
    if (!process.env.API_URL) {
      throw new Error("API_URL not set"); // Uncaught exception!
    }
    return new URL(process.env.API_URL);
  })
});

// After (0.5.0): graceful parser error
const parser = object({
  apiUrl: withDefault(option("--url", url()), () => {
    if (!process.env.API_URL) {
      throw new Error("API_URL not set"); // Automatically caught and formatted
    }
    return new URL(process.env.API_URL);
  })
});

We've also introduced the WithDefaultError class, which accepts structured messages instead of plain strings. This means you can now throw errors with rich formatting that matches the rest of Optique's error output:

import { WithDefaultError, message, envVar } from "@optique/core";

const parser = object({
  // Plain error - automatically converted to text
  databaseUrl: withDefault(option("--db", url()), () => {
    if (!process.env.DATABASE_URL) {
      throw new Error("Database URL not configured");
    }
    return new URL(process.env.DATABASE_URL);
  }),

  // Rich error with structured message
  apiToken: withDefault(option("--token", string()), () => {
    if (!process.env.API_TOKEN) {
      throw new WithDefaultError(
        message`Environment variable ${envVar("API_TOKEN")} is required for authentication`
      );
    }
    return process.env.API_TOKEN;
  })
});

The new envVar message component ensures environment variables are visually distinct in error messages, appearing bold and underlined in colored output or wrapped in backticks in plain text.

More helpful help text with custom default descriptions

Default values in help text can sometimes be misleading, especially when they come from environment variables or are computed at runtime. Optique 0.5.0 allows you to customize how default values appear in help output through an optional third parameter to withDefault().

import { withDefault, message, envVar } from "@optique/core";

const parser = object({
  // Before: shows actual URL value in help
  apiUrl: withDefault(
    option("--api-url", url()),
    new URL("https://api.example.com")
  ),
  // Help shows: --api-url URL [https://api.example.com]

  // After: shows descriptive text
  apiUrl: withDefault(
    option("--api-url", url()),
    new URL("https://api.example.com"),
    { message: message`Default API endpoint` }
  ),
  // Help shows: --api-url URL [Default API endpoint]
});

This is particularly useful for environment variables and computed defaults:

const parser = object({
  // Environment variable
  authToken: withDefault(
    option("--token", string()),
    () => process.env.AUTH_TOKEN || "anonymous",
    { message: message`${envVar("AUTH_TOKEN")} or anonymous` }
  ),
  // Help shows: --token STRING [AUTH_TOKEN or anonymous]

  // Computed value
  workers: withDefault(
    option("--workers", integer()),
    () => os.cpus().length,
    { message: message`Number of CPU cores` }
  ),
  // Help shows: --workers INT [Number of CPU cores]

  // Sensitive information
  apiKey: withDefault(
    option("--api-key", string()),
    () => process.env.SECRET_KEY || "",
    { message: message`From secure storage` }
  ),
  // Help shows: --api-key STRING [From secure storage]
});

Instead of displaying the actual default value, you can now show descriptive text that better explains where the value comes from. This is particularly useful for sensitive information like API tokens or for computed defaults like the number of CPU cores.

The help system now properly handles ANSI color codes in default value displays, maintaining dim styling even when inner components have their own color formatting. This ensures default values remain visually distinct from the main help text.

Comprehensive error message customization

We've added a systematic way to customize error messages across all parser types and combinators. Every parser now accepts an errors option that lets you provide context-specific feedback instead of generic error messages. This applies to primitive parsers, value parsers, combinators, and even specialized parsers in companion packages.

Primitive parser errors

import { option, flag, argument, command } from "@optique/core/primitives";
import { message, optionName, metavar } from "@optique/core/message";

// Option parser with custom errors
const serverPort = option("--port", integer(), {
  errors: {
    missing: message`Server port is required. Use ${optionName("--port")} to specify.`,
    invalidValue: (error) => message`Invalid port number: ${error}`,
    endOfInput: message`${optionName("--port")} requires a ${metavar("PORT")} number.`
  }
});

// Command parser with custom errors
const deployCommand = command("deploy", deployParser, {
  errors: {
    notMatched: (expected, actual) => 
      message`Unknown command "${actual}". Did you mean "${expected}"?`
  }
});

Value parser errors

Error customization can be static messages for consistent errors or dynamic functions that incorporate the problematic input:

import { integer, choice, string } from "@optique/core/valueparser";

// Integer with range validation
const port = integer({
  min: 1024,
  max: 65535,
  errors: {
    invalidInteger: message`Port must be a valid number.`,
    belowMinimum: (value, min) =>
      message`Port ${String(value)} is reserved. Use ${String(min)} or higher.`,
    aboveMaximum: (value, max) =>
      message`Port ${String(value)} exceeds maximum. Use ${String(max)} or lower.`
  }
});

// Choice with helpful suggestions
const logLevel = choice(["debug", "info", "warn", "error"], {
  errors: {
    invalidChoice: (input, choices) =>
      message`"${input}" is not a valid log level. Choose from: ${values(choices)}.`
  }
});

// String with pattern validation
const email = string({
  pattern: /^[^@]+@[^@]+\.[^@]+$/,
  errors: {
    patternMismatch: (input) =>
      message`"${input}" is not a valid email address. Use format: user@example.com`
  }
});

Combinator errors

import { or, multiple, object } from "@optique/core/constructs";

// Or combinator with custom no-match error
const format = or(
  flag("--json"),
  flag("--yaml"),
  flag("--xml"),
  {
    errors: {
      noMatch: message`Please specify an output format: --json, --yaml, or --xml.`,
      unexpectedInput: (token) =>
        message`Unknown format option "${token}".`
    }
  }
);

// Multiple parser with count validation
const inputFiles = multiple(argument(string()), {
  min: 1,
  max: 5,
  errors: {
    tooFew: (count, min) =>
      message`At least ${String(min)} file required, but got ${String(count)}.`,
    tooMany: (count, max) =>
      message`Maximum ${String(max)} files allowed, but got ${String(count)}.`
  }
});

Package-specific errors

Both @optique/run and @optique/temporal packages have been updated with error customization support for their specialized parsers:

// @optique/run path parser
import { path } from "@optique/run/valueparser";

const configFile = option("--config", path({
  mustExist: true,
  type: "file",
  extensions: [".json", ".yaml"],
  errors: {
    pathNotFound: (input) =>
      message`Configuration file "${input}" not found. Please check the path.`,
    notAFile: (input) =>
      message`"${input}" is a directory. Please specify a file.`,
    invalidExtension: (input, extensions, actual) =>
      message`Invalid config format "${actual}". Use ${values(extensions)}.`
  }
}));

// @optique/temporal instant parser
import { instant, duration } from "@optique/temporal";

const timestamp = option("--time", instant({
  errors: {
    invalidFormat: (input) =>
      message`"${input}" is not a valid timestamp. Use ISO 8601 format: 2024-01-01T12:00:00Z`
  }
}));

const timeout = option("--timeout", duration({
  errors: {
    invalidFormat: (input) =>
      message`"${input}" is not a valid duration. Use ISO 8601 format: PT30S (30 seconds), PT5M (5 minutes)`
  }
}));

Error customization integrates seamlessly with Optique's structured message format, ensuring consistent styling across all error output. The system helps you provide helpful, actionable feedback that guides users toward correct usage rather than leaving them confused by generic error messages.

Looking forward

This release focuses on improving the developer experience without breaking existing code. Every new feature is opt-in, and all changes maintain backward compatibility. We believe these improvements make Optique more pleasant to work with, especially when building user-friendly CLI applications that need clear error messages and helpful documentation.

We're grateful to the community members who suggested these improvements and helped shape this release through discussions and issue reports. Your feedback continues to drive Optique's evolution toward being a more capable and ergonomic CLI parser for TypeScript.

To upgrade to Optique 0.5.0, simply update your dependencies:

npm update @optique/core @optique/run
# or
deno update

For detailed migration guidance and API documentation, please refer to the official documentation. While no code changes are required, we encourage you to explore the new error customization options and help text improvements to enhance your CLI applications.

I have this bad habit. When something annoys me enough times,
I end up building a library for it. This time, it was CLI validation code.

See, I spend a lot of time reading other people's code. Open source projects,
work stuff, random GitHub repos I stumble upon at 2 AM. And I kept noticing this
thing: every CLI tool has the same ugly validation code tucked away somewhere.
You know the kind:

if (!opts.server && opts.port) {
  throw new Error("--port requires --server flag");
}

if (opts.server && !opts.port) {
  opts.port = 3000; // default port
}

// wait, what if they pass --port without a value?
// what if the port is out of range?
// what if...

It's not even that this code is hard to write. It's that it's everywhere.
Every project. Every CLI tool. The same patterns, slightly different flavors.
Options that depend on other options. Flags that can't be used together.
Arguments that only make sense in certain modes.

And here's what really got me: we solved this problem years ago for other types
of data. Just… not for CLIs.

The problem with validation

There's this blog post that completely changed how I think about parsing.
It's called Parse, don't validate by Alexis King. The gist? Don't parse data
into a loose type and then check if it's valid. Parse it directly into a type
that can only be valid.

Think about it. When you get JSON from an API, you don't just parse it as any
and then write a bunch of if-statements. You use something like Zod to parse
it directly into the shape you want. Invalid data? The parser rejects it. Done.

But with CLIs? We parse arguments into some bag of properties and then spend
the next 100 lines checking if that bag makes sense. It's backwards.

So yeah, I built Optique. Not because the world desperately needed another CLI
parser (it didn't), but because I was tired of seeing—and writing—the same
validation code everywhere.

Three patterns I was sick of validating

Dependent options

This one's everywhere. You have an option that only makes sense when another
option is enabled.

The old way? Parse everything, then check:

const opts = parseArgs(process.argv);
if (!opts.server && opts.port) {
  throw new Error("--port requires --server");
}
if (opts.server && !opts.port) {
  opts.port = 3000;
}
// More validation probably lurking elsewhere...

With Optique, you just describe what you want:

const config = withDefault(
  object({
    server: flag("--server"),
    port: option("--port", integer()),
    workers: option("--workers", integer())
  }),
  { server: false }
);

Here's what TypeScript infers for config's type:

type Config = 
  | { readonly server: false }
  | { readonly server: true; readonly port: number; readonly workers: number }

The type system now understands that when server is false, port literally
doesn't exist. Not undefined, not null—it's not there. Try to access it and
TypeScript yells at you. No runtime validation needed.

Mutually exclusive options

Another classic. Pick one output format: JSON, YAML, or XML. But definitely not
two.

I used to write this mess:

if ((opts.json ? 1 : 0) + (opts.yaml ? 1 : 0) + (opts.xml ? 1 : 0) > 1) {
  throw new Error('Choose only one output format');
}

(Don't judge me, you've written something similar.)

Now?

const format = or(
  map(option("--json"), () => "json" as const),
  map(option("--yaml"), () => "yaml" as const),
  map(option("--xml"), () => "xml" as const)
);

The or() combinator means exactly one succeeds. The result is just
"json" | "yaml" | "xml". A single string. Not three booleans to juggle.

Environment-specific requirements

Production needs auth. Development needs debug flags. Docker needs different
options than local. You know the drill.

Instead of a validation maze, you just describe each environment:

const envConfig = or(
  object({
    env: constant("prod"),
    auth: option("--auth", string()),      // Required in prod
    ssl: option("--ssl"),
    monitoring: option("--monitoring", url())
  }),
  object({
    env: constant("dev"),
    debug: optional(option("--debug")),    // Optional in dev
    verbose: option("--verbose")
  })
);

No auth in production? Parser fails immediately. Trying to access --auth in
dev mode? TypeScript won't let you—the field doesn't exist on that type.

“But parser combinators though…”

I know, I know. “Parser combinators” sounds like something you'd need
a CS degree to understand.

Here's the thing: I don't have a CS degree. Actually, I don't have any degree.
But I've been using parser combinators for years because they're actually… not
that hard? It's just that the name makes them sound way scarier than they are.

I'd been using them for other stuff—parsing config files, DSLs, whatever.
But somehow it never clicked that you could use them for CLI parsing until
I saw Haskell's optparse-applicative. That was a real “wait, of course”
moment. Like, why are we doing this any other way?

Turns out it's stupidly simple. A parser is just a function. Combinators are
just functions that take parsers and return new parsers. That's it.

// This is a parser
const port = option("--port", integer());

// This is also a parser (made from smaller parsers)
const server = object({
  port: port,
  host: option("--host", string())
});

// Still a parser (parsers all the way down)
const config = or(server, client);

No monads. No category theory. Just functions. Boring, beautiful functions.

TypeScript does the heavy lifting

Here's the thing that still feels like cheating: I don't write types for my CLI
configs anymore. TypeScript just… figures it out.

const cli = or(
  command("deploy", object({
    action: constant("deploy"),
    environment: argument(string()),
    replicas: option("--replicas", integer())
  })),
  command("rollback", object({
    action: constant("rollback"),
    version: argument(string()),
    force: option("--force")
  }))
);

// TypeScript infers this type automatically:
type Cli = 
  | { 
      readonly action: "deploy"
      readonly environment: string
      readonly replicas: number
    }
  | { 
      readonly action: "rollback"
      readonly version: string
      readonly force: boolean
    }

TypeScript knows that if action is "deploy", then environment exists but
version doesn't. It knows replicas is a number. It knows force is
a boolean. I didn't tell it any of this.

This isn't just about nice autocomplete (though yeah, the autocomplete is great).
It's about catching bugs before they happen. Forget to handle a new option
somewhere? Code won't compile.

What actually changed for me

I've been dogfooding this for a few weeks. Some real talk:

I delete code now. Not refactor. Delete. That validation logic that used to
be 30% of my CLI code? Gone. It feels weird every time.

Refactoring isn't scary. Want to know something that usually terrifies me?
Changing how a CLI takes its arguments. Like going from --input file.txt to
just file.txt as a positional argument. With traditional parsers,
you're hunting down validation logic everywhere. With this?
You change the parser definition, TypeScript immediately shows you every place
that breaks, you fix them, done. What used to be an hour of “did I catch
everything?” is now “fix the red squiggles and move on.”

My CLIs got fancier. When adding complex option relationships doesn't mean
writing complex validation, you just… add them. Mutually exclusive groups?
Sure. Context-dependent options? Why not. The parser handles it.

The reusability is real too:

const networkOptions = object({
  host: option("--host", string()),
  port: option("--port", integer())
});

// Reuse everywhere, compose differently
const devServer = merge(networkOptions, debugOptions);
const prodServer = merge(networkOptions, authOptions);
const testServer = merge(networkOptions, mockOptions);

But honestly? The biggest change is trust. If it compiles, the CLI logic works.
Not “probably works” or “works unless someone passes weird arguments.”
It just works.

Should you care?

If you're writing a 10-line script that takes one argument, you don't need this.
process.argv[2] and call it a day.

But if you've ever:

• Had validation logic get out of sync with your actual options
• Discovered in production that certain option combinations explode
• Spent an afternoon tracking down why --verbose breaks when used with
  --json
• Written the same “option A requires option B” check for the fifth time

Then yeah, maybe you're tired of this stuff too.

Fair warning: Optique is young. I'm still figuring things out, the API might
shift a bit. But the core idea—parse, don't validate—that's solid.
And I haven't written validation code in months.

Still feels weird. Good weird.

Try it or don't

If this resonates:

• Tutorial: Build something real, see if you hate it
• Concepts: Primitives, constructs, modifiers, value parsers,
  the whole thing
• GitHub: The code, issues, angry rants

I'm not saying Optique is the answer to all CLI problems. I'm just saying
I was tired of writing the same validation code everywhere, so I built something
that makes it unnecessary.

Take it or leave it. But that validation code you're about to write?
You probably don't need it.