--- layout: home pageClass: optique-landing title: "Optique: type-safe combinatorial CLI parser for TypeScript" description: >- Model your command-line grammar with composable, type-safe parsers. Mutually exclusive modes, dependent options, inferred result types, help, completion, and man pages all come from the same parser definition. ---

Type-safe CLI parser combinators

Make impossible CLI states unrepresentable.

Model your command-line grammar with composable parsers. Mutually exclusive modes, dependent options, inferred result types, and context-aware completion all come from the same structure.

~~~~ ts twoslash import { object, or } from "@optique/core/constructs"; import { constant, option } from "@optique/core/primitives"; import { firstOf, hostname, ip, port, string } from "@optique/core/valueparser"; // ---cut-before--- const auth = object({ mode: constant("auth"), token: option("--token", string()), key: option("--key", string()), }); const config = object({ mode: constant("config"), host: option("--host", firstOf(ip(), hostname())), port: option("--port", port()), }); const deploy = or(auth, config); ~~~~ ~~~~ ts type Deploy = | { mode: "auth"; token: string; key: string } | { mode: "config"; host: string; port: number }; ~~~~
::: code-group ~~~~ bash [npm] npm add @optique/core @optique/run ~~~~ ~~~~ bash [pnpm] pnpm add @optique/core @optique/run ~~~~ ~~~~ bash [Yarn] yarn add @optique/core @optique/run ~~~~ ~~~~ bash [Deno] deno add --jsr @optique/core @optique/run ~~~~ ~~~~ bash [Bun] bun add @optique/core @optique/run ~~~~ :::

Not a friendlier option builder. A parser-combinator library whose result types are the grammar of your command line.

~~~~ ts twoslash import { object } from "@optique/core/constructs"; import { option } from "@optique/core/primitives"; import { firstOf, hostname, ip, port } from "@optique/core/valueparser"; import { message } from "@optique/core/message"; // ---cut-before--- const host = firstOf(ip(), hostname(), { metavar: "HOST", }); const parser = object({ host: option("--host", host, { description: message`Host to bind to.`, }), port: option("--port", port(), { description: message`Port to listen on.`, }), }); ~~~~ ~~~~ ts twoslash import { message, metavar, optionName } from "@optique/core/message"; // ---cut-before--- const input = "99999"; // The same components compose error messages and help text: const error = message`Expected ${metavar("PORT")} for ${optionName("--port")}, but got ${input}.`; ~~~~ ~~~~ ts twoslash import { object, merge } from "@optique/core/constructs"; import { option } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; // ---cut-before--- const CommonOptions = object({ verbose: option("--verbose"), config: option("--config", string()), }); const DeployOptions = object({ environment: option("--env", string()), }); // One value, fully typed. Share these groups across every command. const deployParser = merge(CommonOptions, DeployOptions); ~~~~ ~~~~ ts twoslash import { object, or } from "@optique/core/constructs"; import { withDefault } from "@optique/core/modifiers"; import type { InferValue } from "@optique/core/parser"; import { argument, command, constant, option } from "@optique/core/primitives"; import { integer, string } from "@optique/core/valueparser"; // ---cut-before--- const cli = or( command("create", object({ action: constant("create"), name: argument(string()), role: option("--role", string()), })), command("list", object({ action: constant("list"), limit: withDefault(option("--limit", integer()), 10), })), command("delete", object({ action: constant("delete"), id: argument(integer()), force: option("--force"), })), ); type Command = InferValue; ~~~~ ~~~~ ts twoslash import { object } from "@optique/core/constructs"; import { dependency } from "@optique/core/dependency"; import { option } from "@optique/core/primitives"; import { choice } from "@optique/core/valueparser"; // ---cut-before--- const mode = dependency( choice(["dev", "prod"] as const), ); const logLevel = mode.derive({ metavar: "LEVEL", mode: "sync", factory: (m) => m === "dev" ? choice(["debug", "info", "warn", "error"]) : choice(["warn", "error"]), defaultValue: () => "dev" as const, }); const parser = object({ mode: option("--mode", mode), logLevel: option("--log-level", logLevel), }); ~~~~ ::: code-group ~~~~ bash [Bash] myapp completion bash >> ~/.bashrc ~~~~ ~~~~ bash [zsh] myapp completion zsh > ~/.zsh/completions/_myapp ~~~~ ~~~~ bash [fish] myapp completion fish > ~/.config/fish/completions/myapp.fish ~~~~ ~~~~ bash [PowerShell] myapp completion pwsh > myapp-completion.ps1 ~~~~ ~~~~ bash [Nushell] myapp completion nu | save myapp-completion.nu ~~~~ ::: ~~~~ ts twoslash import { z } from "zod"; import { bindConfig, createConfigContext } from "@optique/config"; import { object } from "@optique/core/constructs"; import { option } from "@optique/core/primitives"; import { string } from "@optique/core/valueparser"; import { bindEnv, createEnvContext } from "@optique/env"; import { prompt } from "@optique/inquirer"; // ---cut-before--- const envContext = createEnvContext({ prefix: "MYAPP_" }); const configContext = createConfigContext({ schema: z.object({ host: z.string().optional() }), }); // CLI > env > config > interactive prompt const host = prompt( bindEnv( bindConfig(option("--host", string()), { context: configContext, key: "host", }), { context: envContext, key: "HOST", parser: string() }, ), { type: "input", message: "Host:", default: "localhost" }, ); ~~~~ For secrets, use *@optique/keyring* as an async operating-system credential source instead of a config file. Register `keyringContext` with `contexts: [keyringContext]`; outer source wrappers take precedence. Missing credentials allow a fallback, while credential-store errors reject the parse.

Start modeling your CLI.

Sponsor Optique on GitHub