vipvot

Zero-dependency TypeScript port of cobra

Language: TypeScript
Version: 0.4.0
License: MIT
Category: Ecosystem

A Bun-native CLI framework that mirrors Go's cobra/pflag exactly — command groups, flag-group constraints, persistent flags, the five-stage hook chain, and 33 pflag flag types. Differential-tested against a real cobra binary so a CLI written in vipvot translates back to Go cobra by mechanical rewrite. Powers the TypeScript agent-* CLIs in this collection.

Features

Cobra parity — command tree, persistent flags, flag-group constraints, five-stage hook chain

33 of pflag's flag types — scalars, slices, string-to-x maps, IP/mask/CIDR, hex and base64 bytes, durations and counts

Honest about the gaps — IPSlice, IPNetSlice, UintSlice and the niche Func/BoolFunc/TextVar/TimeVar callbacks are documented as not ported, rather than implied

Custom flag types via a pflag.Value-equivalent interface, with the help renderer reading type() and toString() automatically

POSIX/GNU parser — short combining (-vvv, -xVALUE), --no-foo negation, -- terminator

Differential-tested byte-for-byte against a real cobra binary — parser edge cases, help layout, and error wording all pinned against the oracle

Did you mean? — Levenshtein suggestions for unknown subcommands, configurable or disableable

Doc generators — markdown, YAML, reST and roff man pages, format pinned against the cobra oracle (vipvot/doc subpath)

Shell completion — bash, zsh, fish, PowerShell with dynamic value completers

Zero runtime dependencies — ~30 KB minified, ~8.5 KB gzipped, with doc and completion generators lazily loaded so they cost nothing unless imported

Bun-native build for `bun build --compile` single-binary CLIs; published ESM runs on Node 20+ too

Install

Bun

$ bun add vipvot

npm

$ npm install vipvot

Build from Source

$ git clone https://github.com/shhac/vipvot.git && cd vipvot && bun install && bun run build

Usage

>_ Define a root command with flags

$ Command({ use: 'app', short: '...', run: (cmd, args) => {...} })

>_ Add a persistent flag inherited by subcommands

$ cmd.persistentFlags().stringP('config', 'c', '', 'config file')

>_ Mark flags mutually exclusive

$ cmd.markFlagsMutuallyExclusive('json', 'yaml')

>_ Generate markdown docs for the whole command tree

$ import { genMarkdownTree } from 'vipvot/doc'; genMarkdownTree(rootCmd, './docs')

>_ Generate zsh completion

$ import { genZshCompletion } from 'vipvot/completion'; genZshCompletion(rootCmd, process.stdout)