{"id":18214,"library":"cleye","title":"Cleye","description":"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.","status":"active","version":"2.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/privatenumber/cleye","tags":["javascript","cli","command line","argv","parameters","flags","node","typescript"],"install":[{"cmd":"npm install cleye","lang":"bash","label":"npm"},{"cmd":"yarn add cleye","lang":"bash","label":"yarn"},{"cmd":"pnpm add cleye","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only since v2.0.0; requires Node >=12 (or >=18 for ESM). CommonJS require() fails because cleye is pure ESM.","wrong":"const { cli } = require('cleye')","symbol":"cli","correct":"import { cli } from 'cleye'"},{"note":"The package exports a default export as well as named exports. The default export is the same as the named `cli`.","wrong":"import { default as cli } from 'cleye'","symbol":"cli (default import)","correct":"import cli from 'cleye'"},{"note":"Since v2.6.0, composable type helpers are available under the 'cleye/formats' subpath; not exported from main entry.","wrong":"import { NumberFormat } from 'cleye'","symbol":"type helpers from cleye/formats","correct":"import { NumberFormat } from 'cleye/formats'"},{"note":"Re-exported from 'type-flag' for convenience; can be used to define custom flag types.","symbol":"TypeFlag","correct":"import { TypeFlag } from 'cleye'"}],"quickstart":{"code":"import { cli } from 'cleye'\n\nconst argv = cli({\n  name: 'greet',\n  parameters: ['<name>'],\n  flags: {\n    time: {\n      type: String,\n      description: 'Time of day (morning/evening)',\n      default: 'morning'\n    }\n  }\n})\n\nconst greeting = argv.flags.time === 'morning' ? 'Good morning' : 'Good evening'\nconsole.log(`${greeting} ${argv._.name}!`)","lang":"typescript","description":"Shows basic CLI with required parameter and typed flag, parsing argv and using strongly typed outputs."},"warnings":[{"fix":"Upgrade Node.js to v18 or later.","message":"v2.0.0 removed support for Node.js 12. Requires Node >= 18 (or >=12 with --experimental-modules? no, ESM only). Use Node 18+.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use import syntax or dynamic import(). If your project is CJS, upgrade to ESM or use dynamic import().","message":"v2.0.0 made the package ESM-only. CommonJS require() will fail with ERR_REQUIRE_ESM.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Migrate to the new object-based API: cli({ name, parameters, flags, ... })","message":"The old v1 API with `(flags, args)` signature is removed in v2.0.0.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Avoid defining flags named 'help', 'version', etc.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Upgrade to v2.2.0+ and enable `strictFlags: true` to reject unknown flags with suggestions.","message":"In v2.0.0, `strictFlags` option (added in v2.2.0) is not available; unknown flags are silently ignored in older versions.","severity":"gotcha","affected_versions":"<2.2.0"},{"fix":"If using async callback, `await cli(...)` to get the parsed argv. Otherwise, the return type is synchronous.","message":"Async callbacks (v2.0.0+) return a Promise; the `cli()` return type is conditional on whether a callback is provided.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use dynamic import: `const { cli } = await import('cleye')` or convert your project to ESM by setting \"type\": \"module\" in package.json.","cause":"Cleye v2+ is ESM-only and cannot be loaded with CommonJS require().","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/cleye/index.js from /path/to/project/index.js not supported."},{"fix":"Use `import cli from 'cleye'` (ESM) or `const { default: cli } = await import('cleye')`.","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.","error":"TypeError: cli is not a function"},{"fix":"Use `{ type: String }` instead of `{ type: 'string' }`.","cause":"In flag type definitions, type must be a constructor (String, Number, Boolean), not a string literal.","error":"Argument of type 'string' is not assignable to parameter of type 'StringConstructor'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}