Optique: Type-safe combinatorial CLI parser for TypeScript

Type-safe combinatorial CLI parser for TypeScript inspired by Haskell's optparse-applicative and TypeScript's Zod. Build composable parsers for command-line interfaces with full type safety, automatic type inference, and built-in shell completion support for Bash, zsh, fish, PowerShell, and Nushell, plus config file integration and man page generation from the same parser definitions.

[!NOTE] Optique is a parsing library that focuses on extracting and validating command-line arguments. It doesn't dictate your application's structure, handle command execution, or provide scaffolding—it simply transforms command-line input into well-typed data structures.

Why Optique

• Composable by default: Build small parser pieces and combine them into larger CLIs without losing readability or types.
• Types that model real CLI rules: Optional flags, mutually exclusive branches, and dependent options are reflected directly in inferred types.
• One parser, many outputs: Derive help text, shell completions, and (with @optique/man) man pages from the same parser definition.
• Practical integrations: Extend parsers with config files, environment variables, OS credential stores, schema validators, interactive prompts, and git-aware parsing.
• Command discovery: Split larger command trees into files with @optique/discover while keeping parser-driven help and completion.
• Cross-runtime consistency: Use the same parser model in Deno, Node.js, and Bun.

Features

• Parser combinators: object(), or(), merge(), optional(), multiple(), map(), conditional(), passThrough(), and more for composable CLI parsing
• Full type safety: Automatic TypeScript type inference for all parser compositions with compile-time validation
• Rich value parsers: Built-in parsers for strings, numbers, URLs, locales, UUIDs, networking types (port(), ipv4(), hostname(), email(), etc.), Temporal types (via @optique/temporal), Standard Schema validators (via @optique/standard-schema), Zod schemas (via @optique/zod), and Valibot schemas (via @optique/valibot)
• Config file support: Load config from files with Standard Schema validation (via @optique/config), supporting Zod, Valibot, ArkType, and more
• Environment variable support: Bind options to environment variables with type-safe parsing and fallback behavior (via @optique/env)
• OS credential-store support: Fill missing password options from the OS credential store with async fallback behavior (via @optique/keyring)
• Derived defaults: Compute default values from the first-pass parse result without lowering CLI argument priority (via @optique/derived-defaults)
• Interactive prompts: Prompt users for missing values via Inquirer.js or Clack with parser-integrated fallback flows (via @optique/inquirer and @optique/clack)
• Inter-option dependencies: Options whose valid values depend on other options, with dynamic validation and context-aware shell completion
• Async parser support: Type-safe sync/async mode distinction for parsers that validate against external sources like git refs or remote APIs
• Man page generation: Generate Unix man pages directly from parser definitions (via @optique/man), keeping documentation always in sync
• Command discovery: Discover command modules from a directory and dispatch to type-checked handlers (via @optique/discover)
• Shell completion: Automatic completion script generation for Bash, zsh, fish, PowerShell, and Nushell
• Smart error messages: “Did you mean?” suggestions for typos with context-aware error formatting
• Automatic help generation: Beautiful help text with usage formatting, labeled sections, and colored output
• Multi-runtime support: Works seamlessly with Deno, Node.js, and Bun
• CLI integration: Complete CLI setup with run() function including help, version, and completion support

Quick example

import { option, constant } from "@optique/core/primitives";
import { object, or, merge } from "@optique/core/constructs";
import { optional } from "@optique/core/modifiers";
import { string, integer } from "@optique/core/valueparser";
import { run, print } from "@optique/run";

// Reusable parser components
const commonOptions = object({
  verbose: option("-v", "--verbose"),
  config: optional(option("-c", "--config", string())),
});

// Mutually exclusive deployment strategies
const localDeploy = object({
  mode: constant("local" as const),
  path: option("--path", string()),
  port: option("--port", integer({ min: 1000 })),
});

const cloudDeploy = object({
  mode: constant("cloud" as const),
  provider: option("--provider", string()),
  region: option("--region", string()),
  apiKey: option("--api-key", string()),
});

// Compose parsers with type-safe constraints
const parser = merge(
  commonOptions,
  or(localDeploy, cloudDeploy)
);

const config = run(parser, { help: "both" });
// config: {
//   readonly verbose: boolean;
//   readonly config: string | undefined;
// } & (
//   | {
//       readonly mode: "local";
//       readonly path: string;
//       readonly port: number;
//   }
//   | {
//       readonly mode: "cloud";
//       readonly provider: string;
//       readonly region: string;
//       readonly apiKey: string;
//   }
// )

// TypeScript knows exactly what's available based on the mode
if (config.mode === "local") {
  print(`Deploying to ${config.path} on port ${config.port}.`);
} else {
  print(`Deploying to ${config.provider} in ${config.region}.`);
}

Docs

Optique provides comprehensive documentation to help you get started quickly: https://optique.dev/.

New to Optique? Start with the tutorial and then explore the cookbook.

• Why Optique? — What makes Optique different from other CLI libraries
• Tutorial — Step-by-step guide from simple options to nested subcommands
• Cookbook — Practical recipes for common CLI patterns including shell completion

API reference documentation for each package is available on JSR (see below).

Packages

Optique is a monorepo which contains multiple packages. The main package is @optique/core, which provides the shared types and parser combinators. The following is a list of the available packages:

Contributing

Contributions are welcome! Read the contributing guide before working on a change. If you use an AI tool, also read the AI usage policy.