https://github.com/dahlia/optique

Type-safe combinatorial CLI parser for TypeScript
https://github.com/dahlia/optique

cli getopt parser-combinators typescript

Last synced: 5 months ago
JSON representation

Type-safe combinatorial CLI parser for TypeScript

• Host: GitHub
• URL: https://github.com/dahlia/optique
• Owner: dahlia
• License: mit
• Created: 2025-08-19T05:34:10.000Z (6 months ago)
• Default Branch: main
• Last Pushed: 2025-10-02T10:34:28.000Z (5 months ago)
• Last Synced: 2025-10-03T11:51:32.420Z (5 months ago)
• Topics: cli, getopt, parser-combinators, typescript
• Language: TypeScript
• Homepage: http://optique.dev/
• Size: 1.06 MB
• Stars: 441
• Watchers: 4
• Forks: 2
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGES.md
  • License: LICENSE
  • Agents: AGENTS.md

Awesome Lists containing this project

• awesome - dahlia/optique - Type-safe combinatorial CLI parser for TypeScript (TypeScript)

README

          


Optique: Type-safe combinatorial CLI parser for TypeScript

==========================================================

[![JSR][JSR badge]][JSR]

[![npm][npm badge]][npm]

[![GitHub Actions][GitHub Actions badge]][GitHub Actions]

> [!WARNING]

> The API is stabilizing, but may change before the 1.0 release.

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 and zsh.

> [!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]: https://jsr.io/@optique

[JSR badge]: https://jsr.io/badges/@optique/core

[npm]: https://www.npmjs.com/package/@optique/core

[npm badge]: https://img.shields.io/npm/v/@optique/core?logo=npm

[GitHub Actions]: https://github.com/dahlia/optique/actions/workflows/main.yaml

[GitHub Actions badge]: https://github.com/dahlia/optique/actions/workflows/main.yaml/badge.svg

[optparse-applicative]: https://github.com/pcapriotti/optparse-applicative

[Zod]: https://zod.dev/

Quick example

-------------

~~~~ typescript

import { object, option, optional, or, merge, constant } from "@optique/core/parser";

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:

.

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:

| Package                                  | JSR                          | npm                          | Description                              |

| ---------------------------------------- | ---------------------------- | ---------------------------- | ---------------------------------------- |

| [@optique/core](/packages/core/)         | [JSR][jsr:@optique/core]     | [npm][npm:@optique/core]     | Shared types and parser combinators      |

| [@optique/run](/packages/run/)           | [JSR][jsr:@optique/run]      | [npm][npm:@optique/run]      | Runner for Node.js/Deno/Bun              |

| [@optique/temporal](/packages/temporal/) | [JSR][jsr:@optique/temporal] | [npm][npm:@optique/temporal] | [Temporal] value parsers (date and time) |

[jsr:@optique/core]: https://jsr.io/@optique/core

[npm:@optique/core]: https://www.npmjs.com/package/@optique/core

[jsr:@optique/run]: https://jsr.io/@optique/run

[npm:@optique/run]: https://www.npmjs.com/package/@optique/run

[jsr:@optique/temporal]: https://jsr.io/@optique/temporal

[npm:@optique/temporal]: https://www.npmjs.com/package/@optique/temporal

[Temporal]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal