Cleye

2.6.0 verified Sat Apr 25 auth: no javascript

Cleye is a TypeScript-first CLI development tool for Node.js that provides minimal API surface, powerful flag parsing, strongly typed parameters and flags, command support, and automatic --help documentation generation. Current stable version is 2.6.0, actively maintained with monthly releases. Unlike yargs or commander, cleye focuses on type safety and a simple, declarative API with no runtime overhead for type inference. It supports async callbacks, boolean flag negation, strict unknown flag rejection, and composable type helpers via the cleye/formats subpath. Ships its own TypeScript types.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/cleye/index.js from /path/to/project/index.js not supported. ↓

cause Cleye v2+ is ESM-only and cannot be loaded with CommonJS require().

fix

Use dynamic import: const { cli } = await import('cleye') or convert your project to ESM by setting "type": "module" in package.json.

error TypeError: cli is not a function ↓

cause Attempting to use default import incorrectly: `import cli from 'cleye'` works, but using `const cli = require('cleye')` returns an ES module namespace object, not the function.

fix

Use import cli from 'cleye' (ESM) or const { default: cli } = await import('cleye').

error Argument of type 'string' is not assignable to parameter of type 'StringConstructor' ↓

cause In flag type definitions, type must be a constructor (String, Number, Boolean), not a string literal.

fix

Use { type: String } instead of { type: 'string' }.

Warnings

breaking v2.0.0 removed support for Node.js 12. Requires Node >= 18 (or >=12 with --experimental-modules? no, ESM only). Use Node 18+. ↓

fix Upgrade Node.js to v18 or later.

breaking v2.0.0 made the package ESM-only. CommonJS require() will fail with ERR_REQUIRE_ESM. ↓

fix Use import syntax or dynamic import(). If your project is CJS, upgrade to ESM or use dynamic import().

deprecated The old v1 API with `(flags, args)` signature is removed in v2.0.0. ↓

fix Migrate to the new object-based API: cli({ name, parameters, flags, ... })

gotcha Built-in flags like `--help` and `--version` cannot be overridden by user-defined flags. Attempting to define a flag with the same name will be silently ignored or cause a runtime error depending on version. ↓

fix Avoid defining flags named 'help', 'version', etc.

gotcha In v2.0.0, `strictFlags` option (added in v2.2.0) is not available; unknown flags are silently ignored in older versions. ↓

fix Upgrade to v2.2.0+ and enable `strictFlags: true` to reject unknown flags with suggestions.

gotcha Async callbacks (v2.0.0+) return a Promise; the `cli()` return type is conditional on whether a callback is provided. ↓

fix If using async callback, `await cli(...)` to get the parsed argv. Otherwise, the return type is synchronous.

Install

npm install cleye

yarn add cleye

pnpm add cleye

Imports

cli
wrong
```
const { cli } = require('cleye')
```
correct
```
import { cli } from 'cleye'
```
ESM-only since v2.0.0; requires Node >=12 (or >=18 for ESM). CommonJS require() fails because cleye is pure ESM.
cli (default import)
wrong
```
import { default as cli } from 'cleye'
```
correct
```
import cli from 'cleye'
```
The package exports a default export as well as named exports. The default export is the same as the named `cli`.
type helpers from cleye/formats
wrong
```
import { NumberFormat } from 'cleye'
```
correct
```
import { NumberFormat } from 'cleye/formats'
```
Since v2.6.0, composable type helpers are available under the 'cleye/formats' subpath; not exported from main entry.
TypeFlag
```
import { TypeFlag } from 'cleye'
```
Re-exported from 'type-flag' for convenience; can be used to define custom flag types.

Quickstart

Shows basic CLI with required parameter and typed flag, parsing argv and using strongly typed outputs.

import { cli } from 'cleye'

const argv = cli({
  name: 'greet',
  parameters: ['<name>'],
  flags: {
    time: {
      type: String,
      description: 'Time of day (morning/evening)',
      default: 'morning'
    }
  }
})

const greeting = argv.flags.time === 'morning' ? 'Good morning' : 'Good evening'
console.log(`${greeting} ${argv._.name}!`)