{"id":22070551,"url":"https://github.com/bconnorwhite/clee","last_synced_at":"2026-04-13T12:01:15.279Z","repository":{"id":111875571,"uuid":"576805683","full_name":"bconnorwhite/clee","owner":"bconnorwhite","description":"Create CLI applications with glee 🎉","archived":false,"fork":false,"pushed_at":"2023-04-11T23:03:23.000Z","size":192,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-09T03:22:10.086Z","etag":null,"topics":["cli","cli-app","command-line","command-line-parser","node","shell","terminal","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bconnorwhite.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-12-11T03:07:24.000Z","updated_at":"2024-01-12T18:52:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"aa3296ec-7c06-4b25-abfc-4e19e1c18762","html_url":"https://github.com/bconnorwhite/clee","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/bconnorwhite/clee","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bconnorwhite%2Fclee","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bconnorwhite%2Fclee/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bconnorwhite%2Fclee/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bconnorwhite%2Fclee/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bconnorwhite","download_url":"https://codeload.github.com/bconnorwhite/clee/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bconnorwhite%2Fclee/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31751705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cli-app","command-line","command-line-parser","node","shell","terminal","typescript"],"created_at":"2024-11-30T20:17:11.230Z","updated_at":"2026-04-13T12:01:15.255Z","avatar_url":"https://github.com/bconnorwhite.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003eclee\u003c/h1\u003e\n  \u003cimg alt=\"Platform: Node\" src=\"https://img.shields.io/badge/Node-%23339933?logo=node.js\u0026logoColor=white\" /\u003e\n  \u003ca href=\"https://npmjs.com/package/clee\"\u003e\n    \u003cimg alt=\"npm\" src=\"https://img.shields.io/npm/v/clee.svg\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/bconnorwhite/clee\"\u003e\n    \u003cimg alt=\"typescript\" src=\"https://img.shields.io/github/languages/top/bconnorwhite/clee.svg\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n\u003cblockquote align=\"center\"\u003eCreate CLI applications with glee 🎉\u003c/blockquote\u003e\n\n\u003cbr /\u003e\n\n_If I should maintain this repo, please ⭐️_\n\u003ca href=\"https://github.com/bconnorwhite/clee\"\u003e\n  \u003cimg align=\"right\" alt=\"GitHub stars\" src=\"https://img.shields.io/github/stars/bconnorwhite/clee?label=%E2%AD%90%EF%B8%8F\u0026style=social\"\u003e\n\u003c/a\u003e\n\n_DM me on [Twitter](https://twitter.com/bconnorwhite) if you have questions or suggestions._\n\u003ca href=\"https://twitter.com/bconnorwhite\"\u003e\n  \u003cimg align=\"right\" alt=\"Twitter Follow\" src=\"https://img.shields.io/twitter/url?label=%40bconnorwhite\u0026style=social\u0026url=https%3A%2F%2Ftwitter.com%2Fbconnorwhite\"\u003e\n\u003c/a\u003e\n\n---\n\nClee is a library for creating CLI applications with TypeScript. It is designed to be easy to use, and easy to test. It is also easy to break commands into modules, for reuse as an API or CLI.\n\n## Contents\n- [Why Clee?](#why-clee)\n- [Installation](#installation)\n- [Overview](#overview)\n- [Usage](#usage)\n  - [Base Settings](#base-settings)\n  - [Inputs](#inputs)\n    - [Arguments](#arguments)\n    - [Options](#options)\n  - [Parsers](#parsers)\n  - [Action](#action)\n  - [Format](#format)\n  - [Parse](#parse)\n  - [Subcommands](#subcommands)\n  - [Other Settings](#other-settings)\n  - [Types](#types)\n- [Examples](#examples)\n  - [ls](/examples/ls/README.md)\n- [Dependencies](#dependencies)\n- [License](#license)\n\n## Why Clee?\n\n- ✨ TypeScript native\n- 📦 Enables extreme modularity\n- 🧪 Easy to test\n- 🔧 Reusable - call as an API, or parse arguments as a CLI\n- 🤔 Optional user prompting for missing arguments\n\n### Additional Features\n\n- Includes parsers for 11 common types\n- Includes formatters in 5 common patterns\n- Includes configurable [figlet](https://www.npmjs.com/package/figlet) titles\n- Automatically load version from package.json\n\n## Installation\n\n\u003cdetails open\u003e\n  \u003csummary\u003e\n    \u003ca href=\"https://www.npmjs.com/package/clee\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/npm-CB3837?logo=npm\u0026logoColor=white\" alt=\"NPM\" /\u003e\n    \u003c/a\u003e\n  \u003c/summary\u003e\n\n```sh\nnpm install clee\n```\n\n\u003c/details\u003e\n\u003cdetails open\u003e\n  \u003csummary\u003e\n    \u003ca href=\"https://yarnpkg.com/package/clee\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/yarn-2C8EBB?logo=yarn\u0026logoColor=white\" alt=\"Yarn\" /\u003e\n    \u003c/a\u003e\n  \u003c/summary\u003e\n\n```sh\nyarn add clee\n```\n\n\u003c/details\u003e\n\u003cdetails open\u003e\n  \u003csummary\u003e\n    \u003cimg src=\"https://img.shields.io/badge/pnpm-F69220?logo=pnpm\u0026logoColor=white\" alt=\"PNPM\" /\u003e\n  \u003c/summary\u003e\n\n```sh\npnpm add clee\n```\n\n\u003c/details\u003e\n\n## Overview\n\nClee is heavily inspired by [commander](https://github.com/tj/commander.js). The base unit of Clee is a Command. A Command is a function that takes arguments and options, and returns a result:\n\n```ts\nimport clee from \"clee\";\n\nconst command = clee(\"my-command\")\n  .argument(\"[name]\", \"Your name\")\n  .action((name) =\u003e {\n    return `Hello, ${name}!`;\n  });\n```\n\n### Both a Program, and a Function\n\nCommands are reusable as both programs that you can run from the command line, and as functions that you can call from anywhere in your code:\n\n```ts\n// Call as a function\ncommand(\"Bob\");\n\n// Parse arguments from the command line\ncommand.parse();\n```\n\n### Data Flow\n\nCommands have several stages, and each stage can be customized:\n\n- **Parser** - _Converts a raw string to a parsed value_\n- **Action** - _Takes parsed arguments and options, and returns a result_\n- **Formatter** - _Takes the result of an action, and formats it for output to the console_\n\nWhen a Command is called as a function, if follows the following steps:\n\n---\n\n#### Function Data Flow\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ccode\u003e[function input]\u003c/code\u003e -\u003e \u003ccode\u003e[parser]\u003c/code\u003e -\u003e \u003ccode\u003e[action]\u003c/code\u003e -\u003e \u003ccode\u003e[function return]\u003c/code\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n---\n\nWhen a command is parsed from the command line, the result is also formatted and then output to the console:\n\n---\n\n#### CLI Program Data Flow\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ccode\u003e[CLI input]\u003c/code\u003e -\u003e \u003ccode\u003e[parser]\u003c/code\u003e -\u003e \u003ccode\u003e[action]\u003c/code\u003e -\u003e \u003ccode\u003e[formatter]\u003c/code\u003e -\u003e \u003ccode\u003e[CLI output]\u003c/code\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n---\n\n## Usage\n\n### Base Settings\n\nEach command can have a name, title, and description. These are used when generating the help screen:\n\n```ts\nimport clee, { pathParser } from \"clee\";\n\nclee(\"my-program\")\n  .title({ font: \"Slant\" }) // Settings for creating a figlet title\n  .description(\"Description\") // Custom description to display on the help screen\n```\n\nExample help screen:\n```\n\n   ____ ___  __  __      ____  _________  ____ __________ _____ ___\n  / __ `__ \\/ / / /_____/ __ \\/ ___/ __ \\/ __ `/ ___/ __ `/ __ `__ \\\n / / / / / / /_/ /_____/ /_/ / /  / /_/ / /_/ / /  / /_/ / / / / / /\n/_/ /_/ /_/\\__, /     / .___/_/   \\____/\\__, /_/   \\__,_/_/ /_/ /_/\n          /____/     /_/               /____/\n\nDescription\n\nUsage: my-program\n\nOptions:\n  -h, --help  Display help for command\n```\n### Inputs\n\nCommands can have arguments and options. Either can be required or optional.\n\nRequired arguments are denoted using square brackets, while optional arguments are denoted using angle brackets.\n\n```ts\n\"\u003crequired\u003e\"\n\"[optional]\"\n```\n\nAdditionally, three dots can be used to denote a variadic argument. However, only the last argument can be variadic:\n\n```ts\n\"\u003crequired_variadic...\u003e\"\n\"[optional_variadic...]\"\n```\n\n#### Arguments\n\nArguments can be required or optional, and can have a description and a custom parser.\n\n```ts\nimport clee from \"clee\";\n\nclee(\"my-program\")\n  .argument(\"\u003cname\u003e\") // An required argument with no description, using the default string parser\n  .argument(\"[path]\", \"Description\", pathParser) // An optional argument using a custom parser\n```\n\n#### Options\n\nOptions can have both a short and long flag, or a long flag only. They can also have a description, and a custom parser.\n\n```ts\nimport clee, { stringParser } from \"clee\";\n\nclee(\"my-program\")\n  .option(\"--flag\") // An option with no description, using the default boolean parser\n  .option(\"--required\", \"\u003cvalue\u003e\") // A required option\n  .option(\"--header\", \"[value...]\") // An optional variadic option\n  .option(\"-o\", \"--other\", \"Description\", stringParser) // An option using a custom parser\n```\n\n##### Option Values\nValues can be provided to options with either a space or an equals sign.\n\n```\n--flag value\n--flag=value\n```\n###### Compound Flags\nAdditionally, compound flags can be used to group multiple short flags together:\n```\n-abc\n```\n###### Variadic Options\nVariadic options can be provided by listing multiple values, or by repeating the flag multiple times:\n```\n--header value1 value2\n--header value1 --header value2\n```\n\n### Parsers\n\nArguments and Options can both supply custom parsers. Several are provided with clee:\n\n```ts\nimport {\n  parseString,\n  parseBoolean,\n  parseNumber,\n  parseInt,\n  parseFloat,\n  parseJSON,\n  parseDate,\n  parseURL,\n  parsePath,\n  parseFile,\n  parseDirectory,\n  parseCSV\n} from \"clee\";\n```\n\nAdditionally, a few prompt parsers are provided. If no value is provided, these will prompt the user for input, using [Enquirer](https://www.npmjs.com/package/enquirer):\n```ts\nimport {\n  promptString,\n  promptBoolean,\n  promptNumber,\n  promptInt,\n  promptFloat\n} from \"clee\";\n```\n\n### Action\n\nA command's action is called when the command is parsed from the command line. The action can be async, and can return a value, which will be passed to the formatter.\n\n```ts\nimport clee from \"clee\";\n\nclee(\"clee\").action(() =\u003e {\n  console.log(\"Hello from clee\");\n});\n```\n\n### Format\n\nCommands can also have formatters. Formatters are bypassed if a command is called directly, but are used when the command is parsed from the command line:\n\n```ts\nimport clee from \"clee\";\n\nclee(\"clee\")\n  .action(() =\u003e {\n    return [\"line 1\", \"line 2\"];\n  })\n  .format((result) =\u003e {\n    return result.join(\"\\n\");\n  });\n```\n\nSeveral built-in formatters are also included with clee:\n```ts\nimport {\n  formatDefault,\n  formatBuffer,\n  formatJSON,\n  formatJSONPretty,\n  formatStringsToLines\n} from \"clee\";\n```\n\n### Parse\n\nBy default, parse will use `process.argv.slice(2)`, but a custom array can also be provided:\n\n```ts\n// Read from `process.argv.slice(2)`:\ncmd.parse();\n\n// Provide custom arguments:\ncmd.parse([\"one\", \"two\", \"three\"]);\n```\n\n### Subcommands\n\nCommands can also be nested, and have their own arguments, options, actions, and sub-commands.\n\n```ts\nimport clee from \"clee\";\n\nconst sub = clee(\"sub\")\n  .action(() =\u003e {\n    console.log(\"Hello from sub command\");\n  });\n\nclee(\"my-program\")\n  .command(sub);\n```\n\n#### Run\nRun allows you to run a subcommand from a parent command:\n\n```ts\nimport clee from \"clee\";\n\nconst sub = clee(\"sub\")\n  .action(() =\u003e {\n    console.log(\"Hello from sub command\");\n  });\n\nconst cmd = clee(\"my-program\")\n  .command(sub);\n\ncmd.run(\"sub\"); // Hello from sub command\n```\n\n### Other Settings\n\n#### Help\n\nThe help flag can be customized with a short flag, long flag, and description:\n```ts\nimport clee from \"clee\";\n\nclee(\"my-program\")\n  .help(\"-e\", \"--example\", \"Custom help description\");\n```\n\nBy default, `-h` and `--help` are used.\n\n#### Version\n\nA version flag can be added by either hardcoding the value, or by passing a path to a file in project with a package.json:\n\n```ts\nimport clee from \"clee\";\n\nclee(\"my-program\")\n  .version(\"1.0.0\") // Hardcoded version\n\nclee(\"my-program-2\")\n  .version(import.meta.url) // Version from package.json\n```\nIf an absolute path is provided, the nearest package.json's version will be used.\n\nAdditionally, the version flags and description can also be customized:\n```ts\nimport clee from \"clee\";\n\nclee(\"my-program\")\n  .version(\"1.0.0\", \"-e\", \"--example\", \"Custom version description\")\n```\n\nBy default, `-v` and `--version` are used.\n\n### Types\n\nTypes are also provided for deriving various types from a `Command`:\n\n```ts\nimport {\n  CommandName,\n  CommandInput,\n  CommandArguments,\n  CommandOptions,\n  CommandResult,\n  CommandSubCommands\n} from \"clee\";\n\ntype Name = CommandName\u003ctypeof command\u003e;\ntype Input = CommandInput\u003ctypeof command\u003e;\ntype Arguments = CommandArguments\u003ctypeof command\u003e;\ntype Options = CommandOptions\u003ctypeof command\u003e;\ntype Result = CommandResult\u003ctypeof command\u003e;\ntype SubCommands = CommandSubCommands\u003ctypeof command\u003e;\n```\n\n## Examples\n\n- [ls](/examples/ls/README.md) - A simple ls program\n\n\u003cbr /\u003e\n\n\u003ch2 id=\"dependencies\"\u003eDependencies\u003ca href=\"https://www.npmjs.com/package/clee?activeTab=dependencies\"\u003e\u003cimg align=\"right\" alt=\"dependencies\" src=\"https://img.shields.io/librariesio/release/npm/clee.svg\"\u003e\u003c/a\u003e\u003c/h2\u003e\n\n- [enquirer](https://www.npmjs.com/package/enquirer): Stylish, intuitive and user-friendly prompt system. Fast and lightweight enough for small projects, powerful and extensible enough for the most advanced use cases.\n- [figlet](https://www.npmjs.com/package/figlet): Creates ASCII Art from text. A full implementation of the FIGfont spec.\n- [get-module-pkg](https://www.npmjs.com/package/get-module-pkg): Get your module's package.json without importing it\n- [read-boolean](https://www.npmjs.com/package/read-boolean): A simple utility for parsing boolean values from strings.\n- [typed-case](https://www.npmjs.com/package/typed-case): Convert between typesafe string casings\n- [types-json](https://www.npmjs.com/package/types-json): Type checking for JSON objects\n\n\u003ch3 id=\"dev-dependencies\"\u003eDev Dependencies\u003c/h3\u003e\n\n- [@types/figlet](https://www.npmjs.com/package/@types/figlet): TypeScript definitions for figlet\n- [@types/node](https://www.npmjs.com/package/@types/node): TypeScript definitions for Node.js\n- [autorepo](https://www.npmjs.com/package/autorepo): Autorepo abstracts away your dev dependencies, providing a single command to run all of your scripts.\n- [chalk](https://www.npmjs.com/package/chalk): Terminal string styling done right\n\n\u003cbr /\u003e\n\n\u003ch2 id=\"license\"\u003eLicense \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg align=\"right\" alt=\"license\" src=\"https://img.shields.io/npm/l/clee.svg\"\u003e\u003c/a\u003e\u003c/h2\u003e\n\n[MIT](https://opensource.org/licenses/MIT) - _The MIT License_\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbconnorwhite%2Fclee","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbconnorwhite%2Fclee","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbconnorwhite%2Fclee/lists"}