# Optique: type-safe combinatorial CLI parser for TypeScript

> Type-safe combinatorial CLI parser for TypeScript

## Table of Contents

### Guide

- [Why Optique?](/why.md): Discover how Optique brings functional composition to TypeScript CLI development, enabling truly reusable parser components that other libraries can't match through configuration-based approaches.
- [Installation](/install.md): Instructions for installing Optique.
- [Optique tutorial: Build type-safe CLIs step by step](/tutorial.md): This tutorial walks you through building type-safe command-line applications using Optique's parser combinators, starting from simple options to complex subcommands.
- [CLI patterns cookbook](/cookbook.md): Practical recipes for common command-line interface patterns using Optique: subcommands, dependent options, mutually exclusive flags, key–value pairs, and more complex CLI designs with detailed explanations.
- [Common pitfalls](/pitfalls.md)

### Concepts

- [Primitive parsers](/concepts/primitives.md): Primitive parsers are the foundational building blocks that handle basic CLI elements like options, arguments, commands, and constants with full type safety and clear error messages.
- [Value parsers](/concepts/valueparsers.md): Value parsers convert string arguments into strongly-typed values with validation, supporting built-in types like integers, URLs, and UUIDs, plus custom parser creation.
- [Modifying combinators](/concepts/modifiers.md): Modifying combinators enhance existing parsers by making them optional, providing defaults, transforming results, or allowing multiple occurrences while preserving type safety.
- [Construct combinators](/concepts/constructs.md): Construct combinators compose multiple parsers into complex structures using object(), tuple(), seq(), or(), and merge() to build sophisticated CLI interfaces with full type inference.
- [Inter-option dependencies](/concepts/dependencies.md): Inter-option dependencies allow one option's valid values to depend on another option's value, enabling dynamic validation and context-aware shell completion.
- [Derived defaults](/concepts/derived-defaults.md): Compute default values from the first-pass parse result while keeping CLI arguments as the highest-priority source.
- [Shell completion](/concepts/completion.md): Learn how to add shell completion support to your CLI applications using Optique's built-in completion system. Covers Bash, zsh, fish, PowerShell, and Nushell integration, custom suggestions, and native file completion.
- [Man pages](/concepts/man.md): Learn how to generate Unix man pages from your CLI application using Optique's man page generator. Covers man page format, customization options, and integration patterns.
- [Command discovery](/concepts/discover.md): Build command-oriented CLI applications by discovering Optique command modules from the file system and dispatching to command handlers.
- [Structured messages](/concepts/messages.md): Structured messages provide a type-safe way to create rich error messages and help text using template literals with semantic components for options, values, and metavariables.
- [Runners and execution](/concepts/runners.md): Learn about the different ways to execute parsers in Optique: from low-level parsing to high-level process integration with automatic error handling and help text generation.
- [Extending Optique with runtime context](/concepts/extend.md)
- [Testing](/concepts/testing.md): Choose the execution boundary a CLI test should exercise, and understand what each layer of @optique/testing does and does not run.

### Integrations

- [Config file support](/integrations/config.md): Load configuration files with type-safe validation using Standard Schema compatible libraries like Zod, Valibot, and ArkType.
- [Environment variable support](/integrations/env.md): Bind parser fields to environment variables with type-safe parsing and fallback behavior.
- [Keyring password fallback](/integrations/keyring.md): Read secrets from the operating system credential store, with hidden password input for interactive commands and environment overrides for API keys.
- [Clack prompts](/integrations/clack.md): Add Clack prompts as fallback for missing CLI arguments.
- [Inquirer.js prompts](/integrations/inquirer.md): Add Inquirer.js prompts as fallback for missing CLI arguments.
- [Prompt adapters](/integrations/prompt.md): Build prompt-library integrations for Optique with a generic adapter API.
- [Git integration](/integrations/git.md): Git value parsers for validating branches, tags, commits, and remotes using isomorphic-git.
- [LogTape integration](/integrations/logtape.md): Integrate LogTape logging with Optique CLI applications using various parsing strategies for log levels, verbosity flags, and output destinations.
- [Standard Schema integration](/integrations/standard-schema.md): Use any Standard Schema-compatible validator as an Optique value parser.
- [Temporal integration](/integrations/temporal.md): Parse ISO 8601 dates, times, durations, and time zones into Temporal API objects with full type safety and validation.
- [Valibot integration](/integrations/valibot.md): Use Valibot schemas for validating command-line arguments with a lightweight, modular validation library offering minimal bundle size.
- [Zod integration](/integrations/zod.md): Use Zod schemas for validating command-line arguments with seamless integration, type inference, and transformation support.

### Comparison

- [How Optique compares](/compare.md): An honest comparison of Optique with other JavaScript and TypeScript CLI libraries—Commander.js, Yargs, Cliffy, Gunshi, Cleye, cmd-ts, Stricli, oclif, and Clipanion—showing when each is the better choice.
- [Optique vs. Commander.js](/compare/commander.md): How Optique compares to Commander.js—where Commander.js's mature, imperative builder API shines, and where Optique's composable parsers pull ahead.
- [Optique vs. Yargs](/compare/yargs.md): How Optique compares to Yargs—where Yargs's declarative builder with built-in env and config support fits, and where Optique's typed composition pulls ahead.
- [Optique vs. Cliffy](/compare/cliffy.md): How Optique compares to Cliffy—where Cliffy's batteries-included Deno framework excels, and where Optique's typed composition pulls ahead.
- [Optique vs. Gunshi](/compare/gunshi.md): How Optique compares to Gunshi—where Gunshi's clean declarative configuration and plugins fit, and where Optique's typed composition pulls ahead.
- [Optique vs. Cleye](/compare/cleye.md): How Optique compares to Cleye—where Cleye's tiny, strongly-typed flag parser fits, and where Optique's composition and fallback chain pull ahead.
- [Optique vs. cmd-ts](/compare/cmd-ts.md): How Optique compares to cmd-ts—two type-first parsers with similar goals, and where their composition models and built-in fallbacks differ.
- [Optique vs. Stricli](/compare/stricli.md): How Optique compares to Stricli—where Bloomberg's deliberately minimal, no-magic framework fits, and where Optique's richer model pulls ahead.
- [Optique vs. oclif](/compare/oclif.md): How Optique compares to oclif—where Salesforce's full CLI framework with plugins and scaffolding fits, and where Optique's lightweight composition fits.
- [Optique vs. Clipanion](/compare/clipanion.md): How Optique compares to Clipanion—where Yarn's class-based command engine excels, and where Optique's composition and fallback chain pull ahead.