Skip to content

Latest commit

 

History

History

cli

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

@cutils/cli

Declarative CLI builder authored inside the scriptc compilable subset — the command spec is a plain record literal, and scriptc build lowers the whole thing into the app's single static ELF. Zero dependencies; runs under Node unchanged.

The library owns exactly one thing — the seam: argv tokenize → flag-vs-value → effective value → the Standard Schema validate boundary → {opts, args} → dispatch, help, errors, exit code. Every value semantic — coercion, constraints, literal unions, morphs — belongs to the schema you bring (zod, arktype, valibot, or a hand-rolled {validate}). opts typing derives entirely from Standard Schema's types.output phantom channel; an option without a schema is a raw string, which is just the truth about argv.

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}`);
        },
      }),
    },
  }),
);
  • No type field. flag is the only parse fact the library owns; everything else is schema. opts types come 100% from types.output — bring arktype/zod and literal unions, branded types, morphs all flow through.
  • Schemas everywhere or nowhere. schema is optional per option and accepts four shapes: a bare {validate}, a (v) => result function, the mySchema["~standard"] props object, or a whole schema object (an arktype Type, a zod schema). A bare schema object also works as the option entry itself.
  • Validated output is what opts gets. Validators receive the raw argv string and return the parsed value — morphs apply to explicit values and to defaults, which are run through validate() at command() time.
  • Zero-dep primitives built in. str(), num(), int(), bool() are tiny Standard-Schema-shaped validators with the types phantom declared — num({min:0, max:99}) infers opts.x: number and validates, no library required.
  • Exits by return code. run prints and returns a number; it never calls process.exit itself, so it stays unit-testable under plain node --test.

Surface

declare function run<O, const A>(prog: ProgramSpec<O, A>, argv?: string[]): number;
declare function runAsync<O, const A>(prog: ProgramSpec<O, A>, argv?: string[]): Promise<number>;
declare function command<O, const A>(description: string, spec: CommandSpec<O, A>): CommandDef;
declare function str(extra?: BuiltinOpts): OptionSpec & { schema: TypedValidator<string> };
declare function num(extra?: NumOpts): OptionSpec & { schema: TypedValidator<number> };
declare function int(extra?: NumOpts): OptionSpec & { schema: TypedValidator<number> };
declare function bool(extra?: BuiltinOpts): OptionSpec & { flag: true; schema: TypedValidator<boolean> };

run(prog) reads process.argv.slice(2); pass argv explicitly as a test seam or to embed a sub-CLI. runAsync is the async twin — it awaits Promise-returning handlers and Promise-returning validators: runAsync(prog).then((c) => process.exit(c)).

interface ProgramSpec<O, A> {
  name: string;
  version?: string;
  description?: string;
  args?: A;                            // root-level positionals
  options?: O;                         // root-level options
  schema?: SchemaInput;                // validates root { opts, args }
  handler?: (opts, args) => unknown;   // program action (single-command CLIs)
  commands?: Record<string, CommandDef>;
}

interface CommandSpec<O, A> {
  args?: A;                            // (string | ArgSpec)[], in order
  options?: O;                         // record of OptionSpec | schema | function
  schema?: SchemaInput;                // validates { opts, args }
  handler?: (opts: OptsFromOptions<O>, args: ArgsFromSpec<A>) => unknown;
  commands?: Record<string, CommandDef>;  // subcommand map → group node
  alias?: string | string[];
  hidden?: boolean;                    // omit from parent help
}

interface ArgSpec {
  name: string;
  optional?: boolean;   // absent → default else null (never undefined)
  variadic?: boolean;   // collects rest into an array slot (must be last)
  default?: unknown;    // absent-optional value, schema-validated
  description?: string;
  schema?: SchemaInput; // validates each element
}

interface OptionSpec {
  schema?: SchemaInput;   // absent = raw string passthrough
  flag?: boolean;         // consumes no value: --x / --x=false / -x
  optionalValue?: boolean;// --opt bare → true, --opt=v → "v" (no space form)
  variadic?: boolean;     // --tag a b / --tag a --tag b → per-element schema → O[]
  negatable?: boolean;    // flag only: --no-x parses to false
  short?: string;         // one character
  default?: unknown;      // run through validate() in command()
  env?: string;           // absent → process.env[env] when set
  description?: string;
  metavar?: string;       // help hint; defaults to the option name
  hidden?: boolean;       // omit from generated help
}

The program is a root command node: root args/options/handler make a single-command CLI, commands nests to any depth, and a group with a handler also runs as its own default action. Kebab-case option keys normalize opts to camelCase ("template-engine" → opts.templateEngine), matching commander.

Parsing rules

Input Result
--upper flag true
--upper=false / =0 / =1 flag value through the validator → false
--no-x negatable flag → false
--times 3, --times=3 raw "3" → validator's output (e.g. 3)
--opt / --opt=v optionalValue → true / "v" (no space form)
--tag a b, --tag=a, --tag a --tag b variadic → ["a","b"], per-element schema → O[]
-u, -t 3, -t3, -ut3 short flags; flag shorts cluster
a b c (leaf) positionals → args slots; ... tail → array
group leaf … first operand matching a subcommand/alias descends
prog help <path…> prints that node's help
-- end of options; rest are positionals
-h node help unless h is a declared short

Option values may appear anywhere before --. Options before a subcommand token bind the parent; options after it belong to the child. A parent node's opts/args/schema all validate before descent.

Defaults and opts presence

Every declared option key exists in opts. When the flag is absent: the default if one was declared (already validated and morphed at command() time), else false for flags / "" for value-options. A schema on a value-option therefore sees "" for absent input — a schema that rejects "" makes its option effectively required; declare a default to keep it optional. Schema-less options check default cheaply (flag → boolean, else → string).

Custom validators

The seam is one interface:

interface CliValidator<I, O> {           // i.e. StandardValidator
  validate(value: unknown): StandardResult | Promise<StandardResult>;
  types?: { input?: I; output?: O };     // phantom — never read at runtime
}

Declare types.output on a hand-rolled validator and opts picks it up — no library needed:

const port: TypedValidator<number> = {
  validate: (v) => {
    const n = Number(v);
    return Number.isNaN(n) ? { issues: [{ message: `expected a number` }] } : { value: n };
  },
  types: { output: 0 },
};
options: { port: { schema: port } }  // opts.port: number

Async validators are rejected with a clear error — Promise results are never awaited.

Migrating from commander

Coming from commander? The shape is mostly mechanical: one declarative spec instead of chained calls, schemas instead of argParser/parseArg callbacks, and opts inferred rather than OptionValues.

commander @cutils/cli Migration notes
.option() / .argument() chaining one command() literal declarative spec = the static schema; no mutation
opts untyped (OptionValues) opts inferred from schemas via types.output the schema carries the type
absent option is undefined zero value, default, or null (optional args) no | undefined unions in the subset
<req> / [opt] / <v...> args "name" / {optional:true} / {variadic:true} ArgSpecs same arity model; schemas type each element
variadic options addOption-style {variadic: true} — also repeatable (--x a --x b) per-element schema → O[]
--opt [val] optional values {optionalValue: true} bare → true, =v → "v"; no space form
.env() fallback env: "VAR" on the OptionSpec env string still goes through validate()
--no-x negated flags {flag: true, negatable: true} explicit, not automatic
argParser / parseArg processing schema: Standard-Schema seam morphs cover coercion, collect, custom types
subcommand trees (.command().command()) nested commands: records options before the token bind the parent
.alias() alias: "a" or alias: [...] shows as name|alias in help
.action() + .parseAsync() handler + runAsync(prog) run is sync; async handlers/validators need runAsync
process.exit inside the framework run/runAsync return the code; caller exits testable under node --test, no hidden exits
program action + program-level options handler/options/args/schema on ProgramSpec the program is a root command node
help <cmd> prog help <path…> pseudo-command walks the tree
hooks (preAction, postAction) not built command-level schema covers validation; hooks are v2
choices/conflicts/implies/preset not built schema / command-schema territory
configureHelp/exitOverride/executables not built fixed conventions; single-ELF model

Notes

  • Parse throughput is benchmarked in bench/apps (Node: node bench-node.mjs; ELF: bash bench-elf.sh) — ~840k ops/s on an options parse vs commander's ~460k and node:util.parseArgs's ~530k (measured 2026-11-08, Node 24, darwin-arm64). Binary size vs a hand-rolled argv baseline is measured and recorded in packages/cli/AGENTS.md.
  • Requires Node >= 22 at dev/build time; the compiled ELF has no Node dependency.