Optique

Optique provides a suite of tools for building robust CLIs:

• Parser Combinators: Use object(), or(), merge(), optional(), multiple(), map(), conditional(), and passThrough() to build complex parsers.
• Type Safety: Automatic TypeScript type inference for all compositions.
• Rich Value Parsers: Built-in support for strings, numbers, URLs, locales, UUIDs, networking types (port(), ipv4(), hostname(), email()), and Temporal types.
• Validation Integrations: Support for Standard Schema, Zod, and Valibot.
• Configuration & Environment: Load settings from config files (@optique/config) or environment variables (@optique/env).
• Interactive Fallbacks: Prompt users for missing values using @optique/inquirer or @optique/clack.
• Documentation & Shell Support: Automatically derive help text, man pages (@optique/man), and shell completions (Bash, zsh, fish, PowerShell, Nushell) from your parser definitions.
• Command Discovery: Use @optique/discover to split large command trees into separate files.

Deciding between Optique and Commander.js depends on your CLI's complexity and requirements:

Choose Commander.js if:

• You want the most widely known Node.js CLI API with abundant community examples.
• Your CLI is a flat list of flags and simple subcommands.
• You only need simple pairwise flag conflicts (using Option.conflicts()).
• You prefer an imperative, incremental builder style.

Choose Optique if:

• You have complex mutually exclusive groups of options and want them enforced by the type system.
• You need to share and recompose option sets as first-class values across multiple commands.
• You want a unified model for resolving values from CLI args, environment variables, config files, and interactive prompts.
• You want automatic generation of --help, shell completions (5 shells), and man pages from a single definition.
• You want built-in schema validation using Standard Schema-compatible validators (like Zod or Valibot).

Choosing between Optique and oclif depends on whether you need a full CLI framework or a lightweight parsing library.

oclif (Framework)

• Best for: Large, extensible CLI products requiring a plugin system, command scaffolding, file-based command discovery, and automatic README/help generation.
• Key Features: Mature plugin ecosystem, lifecycle hooks, and rich declarative flag relationships (e.g., exclusive, exactlyOne).
• Trade-offs: Higher runtime footprint and a rigid project structure.

Optique (Library)

• Best for: Focused tools, lightweight applications, or when you want to bring your own command loader/structure.
• Key Features: Zero-dependency core, type-safe discriminated unions for mutually exclusive option groups, and composable resolution layers (CLI > Env > Config > Prompt).
• Trade-offs: Does not provide scaffolding, plugin systems, or automatic documentation generation.

While oclif handles flag-to-flag relationships (like exclusive: ['otherFlag']), Optique excels at making entire option groups mutually exclusive using the or() construct. This approach ensures that the resulting parsed value is a discriminated union, meaning the TypeScript type explicitly reflects which branch was chosen, preventing invalid states at the type level.

import { object, or } from "@optique/core/constructs";
import type { InferValue } from "@optique/core/parser";
import { constant, option } from "@optique/core/primitives";
import { string, integer } from "@optique/core/valueparser";

const auth = object({
  mode: constant("auth"),
  token: option("--auth-token", string()),
  key: option("--auth-key", string()),
});

const config = object({
  mode: constant("config"),
  file: option("--config-file", string()),
  port: option("--config-port", integer()),
});

const parser = or(auth, config);
type Value = InferValue<typeof parser>;
// Value is a discriminated union: exactly one of the branches above, never a mix.

The @optique/derived-defaults package enables CLI applications to compute default values based on the results of the first-pass parse. This allows for a clear priority hierarchy when resolving values:

1. CLI arguments: Explicitly provided flags/arguments take highest priority.
2. Derived defaults: Values computed from the first-pass parse result.
3. Static defaults: Standard default values defined within the Optique parser.

Key features include:

• Two-pass defaults: Values are derived from already parsed CLI values.
• Async resolver support: Works with runAsync() and runWith().
• Fallback validation: Derived values are validated through the wrapped Optique parser.
• Custom help text: Supports help text for values computed at runtime.
• Composable contexts: Integrates with Optique's context system.

// Priority: CLI arguments > derived defaults > static defaults

Optique uses a structured message system to create rich, type-safe error messages and help text. Instead of using plain strings, you use the message template literal function to embed semantic components. This separates content from presentation, ensuring consistent styling (colors, quotes, italics) for CLI elements like option names, user values, and metavariables across your entire application.

Key benefits include:

• Consistency: All messages follow the same visual conventions.
• Semantic Clarity: Distinguishes between user input, CLI flags, and environment variables.
• Automatic Formatting: Handles colors and terminal-specific features like clickable hyperlinks.

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

// Simple text message
const greeting = message`Welcome to the application!`;

// Message with embedded values
const error = message`Expected port between ${minPort} and ${maxPort}, got ${actualPort}.`;

// Message with CLI-specific elements
const optionError = message`Option ${optionName("--port")} requires a valid number.`;