# @optique/run

> Type-safe combinatorial command-line interface parser

Latest version **1.3.6** (published 2026-10-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install @optique/run
pnpm add @optique/run
yarn add @optique/run
bun add @optique/run
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.3.6 |
| Published | 2026-10-14 |
| First published | 2025-08-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.0.0 |
| Dependencies | 1 |
| Unpacked size | 139.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 738 |
| Author | Hong Minhee |
| Maintainers | hongminhee |
| Keywords | CLI, command-line, commandline, parser, getopt, optparse |

## Links

- npm: https://www.npmjs.com/package/@optique/run
- Repository: https://github.com/dahlia/optique
- Homepage: https://optique.dev/
- Issues: https://github.com/dahlia/optique/issues
- Funding: https://github.com/sponsors/dahlia
- npm.io page: https://npm.io/package/@optique/run

## Dependencies (1)

- [@optique/core](https://npm.io/package/@optique/core.md) 1.3.6

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 1.3.6 (latest) — 2026-10-14
- 1.4.0-dev.2928 (dev) — 2026-10-27
- 1.4.0-dev.2899 — 2026-10-18
- 1.4.0-dev.2897 — 2026-10-18
- 1.4.0-dev.2895 — 2026-10-18
- 1.4.0-dev.2893 — 2026-10-18
- 1.4.0-dev.2892 — 2026-10-14
- 1.2.13 — 2026-10-14
- 1.1.13 — 2026-10-14
- 1.0.15 — 2026-10-14
- 1.0.15-dev.2887 — 2026-10-14
- 1.0.15-dev.2883 — 2026-10-14
- 1.0.15-dev.2880 — 2026-10-14
- 1.0.15-dev.2873 — 2026-10-14
- 1.0.15-dev.2854 — 2026-10-13
- … 981 more at https://npm.io/package/@optique/run/versions

## README

@optique/run
============

Process-integrated CLI parser for Node.js, Bun, and Deno that provides a
batteries-included interface for *@optique/core* with automatic `process.argv`
handling, `process.exit()`, and terminal capabilities.


When to use @optique/run
------------------------

Use *@optique/run* when:

 -  Building CLI applications for Node.js, Bun, or Deno
 -  You want automatic `process.argv` parsing and `process.exit()` handling
 -  You need automatic terminal capability detection (colors, width)
 -  You prefer a simple, batteries-included approach

Use *@optique/core* instead when:

 -  Building web applications or libraries
 -  You need full control over argument sources and error handling
 -  Working in environments without `process` (browsers, web workers)
 -  Building reusable parser components

Built-in help, version, and completion are parser-aware.  Optique only
intercepts `help`, `version`, `completion`, `--help`, `--version`,
`--completion`, and configured aliases when the user parser leaves them
unconsumed.  If your parser uses the same token sequence as ordinary
data, the parse result wins.


Installation
------------

~~~~ bash
deno add jsr:@optique/run jsr:@optique/core
npm  add     @optique/run     @optique/core
pnpm add     @optique/run     @optique/core
yarn add     @optique/run     @optique/core
~~~~


Quick example
-------------

~~~~ typescript
import { run } from "@optique/run";
import { option, argument } from "@optique/core/primitives";
import { object } from "@optique/core/constructs";
import { string, integer } from "@optique/core/valueparser";

const parser = object({
  name: argument(string()),
  age: option("-a", "--age", integer()),
  verbose: option("-v", "--verbose"),
});

// Automatically uses process.argv, handles errors and help, exits on completion
const config = run(parser);

console.log(`Hello ${config.name}!`);
if (config.age) console.log(`You are ${config.age} years old.`);
if (config.verbose) console.log("Verbose mode enabled.");
~~~~

Run it:

~~~~ bash
$ node cli.js Alice --age 25 --verbose
Hello Alice!
You are 25 years old.
Verbose mode enabled.
~~~~


Shell completion
----------------

*@optique/run* automatically supports shell completion for Bash, zsh, fish,
PowerShell, and Nushell.  Enable completion by adding the `completion` option
to your `run()` configuration:

~~~~ typescript
import { run } from "@optique/run";
import { option, argument } from "@optique/core/primitives";
import { object } from "@optique/core/constructs";
import { string, choice } from "@optique/core/valueparser";

const parser = object({
  format: option("-f", "--format", choice(["json", "yaml", "xml"])),
  input: argument(string({ metavar: "FILE" })),
  verbose: option("-v", "--verbose"),
});

const config = run(parser, {
  completion: "both"
});
~~~~

Users can then generate and install completion scripts:

~~~~ bash
# Bash
myapp completion bash > ~/.bashrc.d/myapp.bash
source ~/.bashrc.d/myapp.bash

# zsh
myapp completion zsh > ~/.zsh/completions/_myapp

# fish
myapp completion fish > ~/.config/fish/completions/myapp.fish

# PowerShell
myapp completion pwsh > myapp-completion.ps1
. ./myapp-completion.ps1

# Nushell
myapp completion nu | save myapp-completion.nu
source myapp-completion.nu
~~~~

The completion system automatically provides intelligent suggestions for:

 -  Option names and aliases (`--format`, `-f`)
 -  Option values (`--format json`, `--format=yaml`)
 -  Subcommands and arguments
 -  File paths (when using `path()` value parser)

For more details, see the [completion guide].

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

For more resources, see the [docs] and the [*examples/*](/examples/) directory.

[completion guide]: https://optique.dev/concepts/completion
[docs]: https://optique.dev/

---
_Source: https://npm.io/package/@optique/run · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._