Skip to content
clibuilder

Introduction

clibuilder is a library for building command line applications in Node.js. You describe your CLI as a tree of commands; clibuilder parses process.argv, resolves which command was invoked, validates the arguments and options against the schemas you declared, loads the config file if the command asks for one, and calls your run().

The core idea is that a command’s declaration is its type. When you write:

command({
  name: 'sum',
  arguments: [{ name: 'values', description: 'values to add', type: z.array(z.number()) }],
  options: { verbose: { description: 'be chatty' } },
  run(args) {
    // args.values: number[]
    // args.verbose: boolean | undefined
  }
})

there is no second place to declare the shape of args — it is inferred from arguments and options, using zod (re-exported as z).

What it does

Section titled “What it does”
  • Commands and sub-commands — my-cli repo create nests to any depth, with aliases. See Commands.
  • Typed arguments and options — declared with zod, inferred into run(args), validated before run() is reached. See Arguments & Options.
  • Config files — JSON, YAML, cjs, or mjs, resolved by convention from the CLI name, and validated per command against a zod schema. See Configuration.
  • Plugins — commands published as separate packages, loaded through the config file. See Plugins.
  • A generated help message — --help at every level, built from the descriptions you already wrote.
  • A UI object — this.ui.info/warn/error/debug, with display level driven by --verbose, --silent, and --debug-cli. See UI.
  • A test helper — testCommand() runs a command in-process and returns its result plus the messages it printed.
  • An opt-in startup cache — enableCompileCache() turns on Node’s V8 compile cache from your bin script.

What’s new in v8

Section titled “What’s new in v8”
  • Standalone CLI support. name and version are now required options on cli() rather than being read from package.json, so a bundled, single-file CLI works without shipping its manifest.
  • Plugins are loaded through config. Earlier versions scanned node_modules to discover plugins. Now the config file lists them explicitly, which is dramatically faster to start and works with Yarn PnP and pnpm.
  • keywords drive plugin lookup. The plugins search and plugins list commands use them.
  • ESM is distributed alongside CJS.

Where next

Section titled “Where next”