@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.
argsnames required positionals, in order. Extra positionals are anunexpected argumenterror.optionsentries areOptionSpec, a whole schema object, or a bare(v) => resultfunction — discriminated by~standard/validatepresence (ortypeof === "function").OptionSpechas notype:flag(consumes no value) is the only parse fact;schemaadds validation + typing;short,default(validated throughvalidate()atcommand()),description,metavar(help hint, defaults to the name).- Validators receive the raw argv string; the returned
valueis whatoptsgets — morphs apply to explicit values and defaults. Absent options:default, elsefalsefor flags /""for value-options — a schema that rejects""is effectively required. str()/num()/int()/bool()builtins are zero-dep Standard-Schema-shaped validators withtypes.outputdeclared —num({min, max})both infersopts.x: numberand enforces bounds.- Foreign schemas plug straight in:
schema: myZod,schema: myArktype,schema: mySchema["~standard"], or drop a whole schema object in as the option entry itself. Async validators are rejected cleanly. - Parsing:
--opt,--opt=v,--opt v,-s,-s v,-sV, clustered flag shorts (-ut3),--flag=false,--end-of-options,-h(yields to a declaredshort: "h"). - Generated:
--help/-hat program and command level,--version, unknown-command suggestions, labelled errors. runreturns the exit code and never exits itself:process.exit(run({...})), or passargvas a test seam.
See the package README for the full surface and the commander divergence table.