{"id":15775929,"url":"https://github.com/agentender/cli-forge","last_synced_at":"2026-04-09T01:03:05.540Z","repository":{"id":254533444,"uuid":"846758549","full_name":"AgentEnder/cli-forge","owner":"AgentEnder","description":"Powerful, Composable CLI Tools","archived":false,"fork":false,"pushed_at":"2026-02-17T00:29:48.000Z","size":4264,"stargazers_count":6,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-17T07:27:57.486Z","etag":null,"topics":["cli","nodejs","toolkit"],"latest_commit_sha":null,"homepage":"http://craigory.dev/cli-forge/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AgentEnder.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-08-23T22:29:35.000Z","updated_at":"2026-02-17T00:27:47.000Z","dependencies_parsed_at":"2024-08-28T06:21:44.766Z","dependency_job_id":"c32c1b88-edc6-4ff2-bfe4-172321998e97","html_url":"https://github.com/AgentEnder/cli-forge","commit_stats":{"total_commits":88,"total_committers":1,"mean_commits":88.0,"dds":0.0,"last_synced_commit":"e5e7380e743a6609827080c07da24408209a77de"},"previous_names":["agentender/cli-forge"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/AgentEnder/cli-forge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgentEnder%2Fcli-forge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgentEnder%2Fcli-forge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgentEnder%2Fcli-forge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgentEnder%2Fcli-forge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AgentEnder","download_url":"https://codeload.github.com/AgentEnder/cli-forge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgentEnder%2Fcli-forge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29606368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T06:47:36.664Z","status":"ssl_error","status_checked_at":"2026-02-19T06:45:47.551Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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","nodejs","toolkit"],"created_at":"2024-10-04T17:03:44.279Z","updated_at":"2026-04-09T01:03:05.526Z","avatar_url":"https://github.com/AgentEnder.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- BEGIN LOGO --\u003e\n\n![CLI Forge Logo](./docs-site/static/img/logo.svg)\n\n\u003c!-- END LOGO --\u003e\n\n# CLI Forge\n\n**A type-safe CLI builder for Node.js with first-class TypeScript support.**\n\n✨ Proudly built with [Nx](https://nx.dev) ✨.\n\nCLI Forge is a modern framework for building command-line interfaces in Node.js, designed with TypeScript developers in mind. While inspired by established tools like [yargs](https://yargs.js.org/), [commander](https://www.npmjs.com/package/commander), and [vorpal](https://vorpal.js.org/), CLI Forge prioritizes type safety and developer experience above all else.\n\n## Why CLI Forge?\n\n**Type Safety First** — Every option and argument you define is fully typed throughout your application. The library uses TypeScript's type inference to provide accurate intellisense and catch errors at compile time, not runtime.\n\n**Built for Modern Node.js** — Designed from the ground up for TypeScript projects with ESM support, middleware composition, and a clean fluent API that feels natural to use.\n\n**Comprehensive Tooling** — Generate documentation automatically from your CLI definition, test your commands with the built-in test harness, and optionally enable an interactive shell for improved user experience.\n\n## Runtime compatibility\n\nCLI Forge is primarily developed against modern Node.js, and is also compatible with Bun for common CLI execution workflows (for example using `bun run ./bin/my-cli.ts` during development and `bun` for running built output).\n\n## Key Features\n\n- **Full type inference** for parsed arguments based on your option definitions\n- **Flexible option types**: strings, numbers, booleans, arrays, and nested objects\n- **Command hierarchy** with unlimited nesting and inherited options\n- **Middleware system** for transforming arguments before handler execution\n- **Interactive shell** (opt-in) for easier exploration of complex command trees\n- **Automatic documentation generation** to markdown or JSON formats\n- **Configuration file support** with inheritance via `extends`\n- **Built-in test harness** for unit testing your CLI commands\n- **Comprehensive validation** with custom validators, choices, and cross-option constraints\n\n## Quick Start\n\nTo create a new CLI, simply run:\n\n```bash\nnpx cli-forge init my-cli\n```\n\n## Manual Installation\n\nTo install the full command library, run:\n\n```bash\nnpm install cli-forge\n```\n\nThen, create a new file (e.g. `my-cli.ts`), and add the following code:\n\n```js\nimport { cli } from 'cli-forge';\n\ncli('my-cli')\n  .command('hello', {\n    description: 'Say hello to the world',\n    builder: (args) =\u003e\n      args.option('name', {\n        type: 'string',\n        description: 'The name to say hello to',\n      }),\n    handler: (args) =\u003e {\n      console.log(`Hello, ${args.name}!`);\n    },\n  })\n  .forge();\n```\n\n## Usage\n\nSee docs for more examples: [https://craigory.dev/cli-forge/examples](https://craigory.dev/cli-forge/examples)\n\n### Basic Example\n\nTo create a new CLI, save the below code to a file (e.g. `my-cli.js`), and run it with Node.js:\n\n```js\nimport { cli } from 'cli-forge';\n\ncli('my-cli')\n  .command('hello', {\n    description: 'Say hello to the world',\n    builder: (args) =\u003e\n      args.option('name', {\n        type: 'string',\n        description: 'The name to say hello to',\n      }),\n    handler: (args) =\u003e {\n      console.log(`Hello, ${args.name}!`);\n    },\n  })\n  .forge();\n```\n\nThen run the CLI with:\n\n```bash\nnode my-cli.js hello --name \"World\"\n```\n\nThen, to generate documentation for the CLI, run:\n\n```bash\nnpx cli-forge generate-docs my-cli.js\n```\n\nThis should generate a folder called `docs` containing markdown documentation for the CLI. Alternatively, you can pass `--format json` to generate JSON documentation to further process.\n\n## Subshells\n\n`cli-forge` ships with a simplistic subshell to make interactively running commands feel a bit nicer. The subshell is entirely opt-in, and can be enabled by calling `.enableInteractiveShell()` on your top level command.\n\nIf enabled, running any command that has subcommands without specifying a subcommand will drop you into the subshell. This allows you to run subcommands without having to retype the top level command.\n\nSee the [subshell example](https://craigory.dev/cli-forge/examples/interactive-subshell) for more information and a concrete example.\n\nMore improvements to the subshell are planned in the future.\n\n## Generating Documentation\n\n`cli-forge` can generate documentation for your CLI based on the commands and options that you've defined. To generate documentation, run:\n\n```bash\nnpx cli-forge generate-docs my-cli.{js,ts}\n```\n\nBy default, this will generate markdown documentation in a folder called `docs`. You can also pass `--format json` to generate a JSON object representation of your CLI instead. This is useful as a middle step if you want to generate documentation in a different format, or just a different style of markdown.\n\n## How It Compares\n\n### vs. Yargs\n\nCLI Forge shares a similar fluent API style with yargs, but makes different tradeoffs:\n\n**What CLI Forge adds:**\n\n- Superior TypeScript inference that tracks every option through the chain\n- Built-in middleware system for argument transformation\n- Interactive shell support (inspired by vorpal)\n- Integrated documentation generation (`cli-forge generate-docs`)\n- Test harness for unit testing CLI commands\n- Configuration file inheritance with `extends`\n\n**Intentional differences:**\n\n- **No usage string parsing** — To maintain type safety, options must be explicitly declared rather than parsed from usage strings\n- **No unknown option parsing** — Unknown options aren't captured by design; explicit option definitions ensure type safety\n- **No filesystem-based routing** — Commands are registered programmatically for better discoverability and refactoring support\n\n### vs. Commander\n\nCommander offers a lightweight API, while CLI Forge provides more structure:\n\n**CLI Forge advantages:**\n\n- Full TypeScript type inference throughout the argument chain\n- Richer option types (nested objects with typed properties)\n- Middleware composition\n- Built-in configuration file support with inheritance\n- Automatic documentation generation\n- Interactive shell mode\n\n### vs. Vorpal\n\nVorpal pioneered interactive CLI shells but hasn't been maintained since 2018. CLI Forge brings that concept forward:\n\n**Modern improvements:**\n\n- Active maintenance with TypeScript-first design\n- Opt-in interactive shell (not required)\n- Contemporary Node.js and TypeScript support\n- Comprehensive testing utilities\n- Documentation generation tooling\n\n### Design Philosophy\n\nCLI Forge prioritizes **user type safety** over internal implementation purity. While the library uses type assertions internally where necessary due to TypeScript limitations, the public API provides full type inference and safety. The goal is a CLI framework that feels natural in TypeScript projects while catching as many errors as possible at compile time.\n\n## Contributing\n\nContributions are welcome! Please see the [contributing guide](CONTRIBUTING.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentender%2Fcli-forge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentender%2Fcli-forge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentender%2Fcli-forge/lists"}