dahlia / optique

Optique: Type-safe combinatorial CLI parser for TypeScript ========================================================== [![JSR][JSR badge]][JSR] [![npm][npm badge]][npm] [![GitHub Actions][GitHub Actions badge]][GitHub Actions] [![Codecov][Codecov badge]][Codecov] 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. [JSR badge]: https://jsr.io/badges/@optique/core [JSR]: https://jsr.io/@optique [npm badge]: https://img.shields.io/npm/v/@optique/core?logo=npm [npm]: https://www.npmjs.com/package/@optique/core [GitHub Actions badge]: https://github.com/dahlia/optique/actions/workflows/main.yaml/badge.svg [GitHub Actions]: https://github.com/dahlia/optique/actions/workflows/main.yaml [Codecov badge]: https://codecov.io/gh/dahlia/optique/graph/badge.svg?token=Dw50j2DTjG [Codecov]: https://codecov.io/gh/dahlia/optique [optparse-applicative]: https://github.com/pcapriotti/optparse-applicative [Zod]: https://zod.dev/ 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, schema validators, interactive prompts, and git-aware parsing. • *Cross-runtime consistency*: Use the same parser model in Deno, Node.js, and Bun. Features -------- • *Parser combinators*: , , , , , , , , 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 ( , , , , etc.), Temporal types (via *@optique/temporal*), 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*) • *Interactive prompts*: Prompt users for missing values via Inquirer.js with parser-integrated fallback flows (via *@optique/inquirer*) • *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 • *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 function including help, version, and completion support Quick example ------------- ~~~~ typescript 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( ); } else { print( ); } ~~~~ Docs ---- Optique provides comprehensive documentation to help you get started quickly: . 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). [tutorial]:…