@cutils/cli
@cutils/cli
@cutils/cli
Declarative CLI builder in the scriptc-compilable subset — the same source runs under Node and lowers into a native ELF. Zero dependencies. It owns the seam only: argv → validated values → dispatch; all value semantics (coercion, constraints, morphs) belong to the Standard Schema you plug in.
Quickstart
Node
Native
pnpm add @cutils/cli
import { bool, command, int, run, str } from "@cutils/cli";
process.exit(
run({
name: "demo",
version: "1.0.0",
commands: {
greet: command("greet someone", {
args: ["name"],
options: {
upper: bool({ short: "u", description: "uppercase output" }),
times: int({ short: "t", default: 1, max: 10, description: "repeat n times" }),
greeting: str({ short: "g", description: "greeting word" }),
},
handler: (opts, args) => {
// opts: { upper: boolean; times: number; greeting: string } — fully inferred
const who = opts.upper ? args[0].toUpperCase() : args[0];
for (let i = 0; i < opts.times; i++) console.log(`${opts.greeting || "hello"} ${who}`);
},
}),
},
}),
);
scriptc build src/main.ts -o demo
./demo greet -u -t2 world # hello WORLD, twice
./demo greet --help # generated usage + options table
How it works
The command() spec is a plain record literal. OptsFromOptions maps each options entry into the handler’s opts parameter through Standard Schema’s types.output channel — parse rules, types, --help output, and error messages all come from one static schema, no runtime reflection.
- The program is a root command node:
ProgramSpeccarries the sameargs/options/schema/handler/commandsfields as everycommand()spec — a program can be a pure dispatcher, a single-command CLI (nocommandsneeded), or both. argsentries are"name"(required positional) orArgSpec—{name, optional, variadic, default, description, schema}. Optional args absent →defaultelsenull;variadic(last only) collects the rest into an array slot;schemavalidates each element. Handlerargsis a mapped tuple viaArgsFromSpec.optionsentries areOptionSpec, a whole schema object, or a bare(v) => resultfunction — discriminated by~standard/validatepresence (ortypeof === "function").OptionSpec:flag(consumes no value),optionalValue(--optbare →true,--opt=v→"v"),variadic(--tag a b/--tag a --tag b→O[], per-element schema),negatable(flag:--no-x→false),short,default(validated atcommand()),env(process.envfallback),description,metavar,hidden.- Kebab-case option keys normalize
optsto camelCase ("template-engine"→opts.templateEngine). commandsnests to any depth: a group is acommand()whose spec hascommands(handler optional — present = default action). Options before a subcommand token bind the parent; parent opts/args/schema validate before descent.aliasadds invocation names (name|aliasin help).prog help <path…>prints any node’s help.- Validators receive the raw argv string; the returned
valueis whatoptsgets — morphs apply to explicit values and defaults. Absent options:default, elseenv, elsefalsefor flags /""for value-options. str()/num()/int()/bool()builtins are zero-dep Standard-Schema-shaped validators withtypes.outputdeclared.runis fully sync — async handlers or Promise-returning validators are clean errors pointing atrunAsync(prog), which awaits both. Entry idiom:runAsync(prog).then((c) => process.exit(c)).- Parsing:
--opt,--opt=v,--opt v,-s,-s v,-sV, clustered flag shorts (-ut3),--flag=false,--no-x,--end-of-options,-h(yields to a declaredshort: "h"at every level). - Generated:
--help/-hat every node,--version(root), unknown-command suggestions (aliases included), labelled errors.
See the package README for the full surface and the commander migration table.