{"id":18720110,"url":"https://github.com/lokicoule/commandzen","last_synced_at":"2025-08-12T14:39:18.996Z","repository":{"id":149896908,"uuid":"621722507","full_name":"Lokicoule/commandzen","owner":"Lokicoule","description":"A command-line parsing argument library.","archived":false,"fork":false,"pushed_at":"2025-08-03T23:29:59.000Z","size":738,"stargazers_count":2,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-04T01:34:39.934Z","etag":null,"topics":["cli","cli-builder","command-line","command-line-tool","nodejs","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/commandzen","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Lokicoule.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2023-03-31T08:46:49.000Z","updated_at":"2024-11-27T08:36:36.000Z","dependencies_parsed_at":"2023-09-22T00:07:32.269Z","dependency_job_id":"117088d5-bd61-4698-adfe-701236fd2abf","html_url":"https://github.com/Lokicoule/commandzen","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/Lokicoule/commandzen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lokicoule%2Fcommandzen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lokicoule%2Fcommandzen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lokicoule%2Fcommandzen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lokicoule%2Fcommandzen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Lokicoule","download_url":"https://codeload.github.com/Lokicoule/commandzen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lokicoule%2Fcommandzen/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270077906,"owners_count":24523287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-builder","command-line","command-line-tool","nodejs","typescript"],"created_at":"2024-11-07T13:29:30.608Z","updated_at":"2025-08-12T14:39:18.969Z","avatar_url":"https://github.com/Lokicoule.png","language":"TypeScript","readme":"# CommandZen\n\nThe CommandZen Library is a TypeScript library designed to help to create command-line interface (CLI) applications with ease. With a clean and intuitive API, you can register commands, options and execute actions based on user input.\n\n[![Coverage Status](https://coveralls.io/repos/github/Lokicoule/commandzen/badge.svg?branch=main\u0026kill_cache=1)](https://coveralls.io/github/Lokicoule/commandzen?branch=main)\n\n## Table of Contents\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n- [API](#api)\n  - [CliBuilder](#clibuilder)\n  - [Command](#command)\n  - [Option](#option)\n- [Examples](#examples)\n- [Contribution](#contribution)\n- [License](#license)\n\n## Features\n\n- Simple and intuitive API for registering commands/subcommands and options\n- Automatic help generation for commands and subcommands\n- Supports command aliases\n\n## Requirements\n\nTo use **_CommandZen_** library, ensure you have the following requirements in your environment:\n\n- Node.js: _CommandZen_ is a Node.js library. It's recommended to use the latest LTS version of Node.js, which can be downloaded from the [official Node.js website](https://nodejs.org/).\n\n- Module support: _CommandZen_ provides both **_CommonJS_** and **_ECMAScript module (ESM)_** builds. Make sure your project is set up to work with either the _\"dist/cjs/index.js\"_ (**_CommonJS_**) or _\"dist/esm/index.js\"_ (**_ESM_**) files, depending on your preferred module system.\n\n- TypeScript: _CommandZen_ includes TypeScript type definitions in the _\"dist/types/index.d.ts\"_ file. If you are using TypeScript in your project, make sure you have the necessary tooling and configuration to work with the provided type definitions.\n\nTo install and use **_CommandZen_**, follow the installation and usage instructions provided in the [Installation](#installation) and [Usage](#usage) sections of this README.\n\n## Installation\n\nYou can install the CLI Library using NPM:\n\n```sh\nnpm install commandzen\n```\n\n## Usage\n\nTo use CommandZen, you need to define commands and options for your CLI. You can do this using the Command and Option classes provided by the library.\n\n```ts\nimport { CliBuilder, Command, Option } from \"commandzen\";\n\n// Create a new CLI instance\nconst cli = CliBuilder.create({\n  name: \"mycli\",\n  description: \"My CLI tool\",\n});\n\n// Add 'greet' command with options and action\ncli\n  .addCommand(\n    Command.create({\n      name: \"greet\",\n      description: \"Greet the user\",\n      aliases: [\"hello\"],\n    })\n      .addOption(\n        {\n          flag: \"-f, --first-name \u003cname\u003e\",\n          description: \"Provide a name to greet\",\n        },\n        {\n          flag: \"-l, --last-name \u003clastname\u003e\",\n          description: \"Provide a lastname to greet\",\n        }\n      )\n      .registerAction\u003c{ firstName: string; lastName: string }\u003e(\n        ({ firstName, lastName }) =\u003e {\n          console.log(`Hello, ${firstName} ${lastName}!`);\n        }\n      )\n  )\n  // Add a global option to the root command\n  .addOption({\n    flag: \"-v, --version \u003cversion\u003e\",\n    description: \"Provide a version to the root command\",\n  })\n  // Register action for the global option\n  .registerAction\u003c{ version: string }\u003e(({ version }) =\u003e {\n    console.log(`Version: ${version}`);\n  });\n\n// Parse the CLI input\ncli.parse();\n```\n\n## API\n\nThe CommandZen API consists of three classes that you can use to build your CLI:\n\n### CliBuilder\n\nThe CliBuilder class is used to build a CLI (Command Line Interface) application. It provides methods to create, manage, and execute commands and options.\n\n#### Public Methods\n\n- `create(props: CommandProps): CliBuilder`\n\nThis static method creates a new CliBuilder instance with the specified [command properties](#commandprops-type).\n\n```ts\nconst cli = CliBuilder.create({\n  name: \"my-cli\",\n  description: \"A command line application\",\n});\n```\n\n- `addCommand(command: Command): CliBuilder`\n\nThis method adds a [command](#command) to the CLI, with an automatically added help option.\n\n```ts\nconst myCommand = Command.create({\n  name: \"my-command\",\n  description: \"Performs a specific task\",\n});\n\ncli.addCommand(myCommand);\n```\n\n- `addOption(props: OptionProps): CliBuilder`\n\nThis method adds an option to the default command.\n\n```ts\ncli.addOption({\n  flag: \"-v, --verbose\",\n  description: \"Enable verbose output\",\n});\n```\n\n- `setDefaultCommand(command: Command): CliBuilder`\n\nThis method overrides the default [command](#command) with a specified command.\n\n```ts\nconst customDefaultCommand = Command.create({\n  name: \"custom-default\",\n  description: \"Custom default command\",\n});\n\ncli.setDefaultCommand(customDefaultCommand);\n```\n\n- `addGlobalOption(props: OptionProps): CliBuilder`\n  This method recursively adds an option to all commands\n\n```ts\ncli.addGlobalOption({\n  {\n    flag: \"-v, --verbose\",\n    description: \"Verbosity\",\n  }\n})\n```\n\n- `parse(): void`\n\nThis method parses the arguments and executes the appropriate command.\n\n```ts\ncli.parse();\n```\n\n### Command\n\nThe Command class represents a single command or subcommand in a CLI application. It contains options and an action to be executed when the command is called.\n\n#### 1. Public Methods\n\n- `create(props: CommandProps): Command`\n\nThis static method creates a new Command instance with the specified [properties](#commandprops-type).\n\n```ts\nconst myCommand = Command.create({\n  name: \"my-command\",\n  description: \"Performs a specific task\",\n  // Optional\n  aliases: [\"mc\", \"m-c\"],\n  // Optional\n  options: [\n    Option.create({\n      // Option 1\n    }),\n    Option.create({\n      // Option 2\n    }),\n  ],\n  // Optional\n  subcommands: [\n    Command.create({\n      // Subcommand 1\n    }),\n    Command.create({\n      // Subcommand 2\n    }),\n  ],\n});\n```\n\n- `addSubcommand(command: Command): Command`\n\nThis method adds a subcommand to the current command.\n\n```ts\nconst parentCommand = Command.create({\n  name: \"parent\",\n  description: \"Parent command\",\n});\n\nconst childCommand = Command.create({\n  name: \"child\",\n  description: \"Child command\",\n});\n\nparentCommand.addSubcommand(childCommand);\n```\n\n- `addOption(...option: OptionProps[]): Command`\n\nThis method adds one or more [options](#optionprops-type) to the command.\n\n```ts\nconst myCommand = Command.create({\n  name: \"my-command\",\n  description: \"Performs a specific task\",\n}).addOption(\n  {\n    flag: \"-p, --project \u003cpath\u003e\",\n    description: \"Specify the path to the tsconfig.json file\",\n  },\n  {\n    flag: \"-i, --install\",\n    description: \"Install something\",\n  }\n);\n```\n\n- `addAlias(...aliases: string[]): Command`\n\nThis method adds one or more aliases to the command.\n\n```ts\nconst myCommand = Command.create({\n  name: \"my-command\",\n  description: \"Performs a specific task\",\n});\n\nmyCommand.addAlias(\"mc\", \"m-c\");\n```\n\n- `registerAction\u003cT\u003e(callback: (props: T) =\u003e void): Command`\n\nThis method registers an action for the command by attaching a callback function to the command's event.\n\n```ts\nconst myCommand = Command.create({\n  name: \"my-command\",\n  description: \"Performs a specific task\",\n})\n  .addOption({\n    flag: \"-p, --project \u003cname\u003e\",\n    description: \"Specify the name of the project\",\n  })\n  .registerAction\u003c{ project: string }\u003e(({ project }) =\u003e {\n    console.log(`Project: ${project}`);\n  });\n```\n\n- `findOption(flag: string): Option | undefined`\n\nThis method finds an option by its flag (short or long name).\n\n- `findSubcommand(name: string): Command | undefined`\n\nThis method finds a subcommand by its name.\n\n#### 2. CommandProps Type\n\nThe `CommandProps` type is used to define the properties of a `Command` object.\n\n- `name` (string): The name of the command. This is the keyword that users will type to invoke the command in the CLI.\n- `description`: A brief description of the command, which will be displayed in the help output.\n- `aliases` (string[] | optional): An array of alternative names for the command. Users can use any of these aliases to invoke the command.\n- `options` (Option[] | optional): An array of `Option` objects that define the options available for the command. Options can be flags or arguments that modify the behavior of the command.\n- `subcommands` (Map\u003cstring, Command\u003e | optional): A map of subcommands, with the subcommand name as the key and the `Command` object as the value. Subcommands are additional commands that can be invoked as a part of the parent command.\n\n### Option\n\nThe `Option` class represents a command line option and is used to define options for commands in a CLI application. It provides methods to create and manage options, including parsing their flags and setting default values.\n\n#### 1. Public Method\n\n- `create(props: OptionProps): Option`\n\nThis static method creates a new Option instance with the specified [properties](#optionprops-type).\n\n```ts\nconst verboseOption = Option.create({\n  flag: \"-v, --verbose\",\n  description: \"Enable verbose output\",\n});\n```\n\n#### 2. OptionProps Type\n\nThe `OptionProps` type represents the properties of an option and includes the following properties:\n\n- `flag` (string): A string representing the option's flag, such as -v, --verbose.\n- `description` (string): A string describing the option's purpose.\n- `defaultValue` (unknown | undefined): An optional default value for the option.\n\n## Examples\n\nWe have provided some real-world inspired examples to help you understand how to use CommandZen effectively. These examples are located in the `examples` folder.\n\n1. [File Management](https://github.com/lokicoule/commandzen/blob/main/examples/file_management.ts): A simple file management CLI tool inspired by Unix commands such as `cp`, `rm`, and `mv`.\n2. [Request Management](https://github.com/lokicoule/commandzen/blob/main/examples/request_management.ts): A CLI tool (inspired by `curl`) that can send HTTP requests and display the response.\n3. [Package Management](https://github.com/lokicoule/commandzen/blob/main/examples/package_management.ts): A package management CLI tool inspired by `npm` and `yarn` with commands to install, update, and remove packages.\n\nTo run these examples, navigate to the `examples` folder and execute the TypeScript files with `ts-node` or transpile them to JavaScript and run using `node`. Make sure you have the necessary dependencies installed.\n\nExample:\n\n```sh\ncd examples\nts-node file_management.ts\n```\n\nKeep in mind that these examples are meant for educational purposes only and might not cover all possible use cases. They are meant to give you an idea of how to build CLI tools using CommandZen. Feel free to modify and extend these examples to fit your needs.\n\n## Contribution\n\nWe welcome contributions from the community to help improve the CommandZen library! To contribute, please follow these steps:\n\n1. Fork the repository: Click the \"Fork\" button at the top-right corner of the repository page on GitHub to create a copy of the repository under your GitHub account.\n\n2. Clone the forked repository: Clone your forked repository to your local machine using the following command (replace your_username with your GitHub username):\n\n```sh\ngit clone https://github.com/your_username/commandzen.git\n```\n\n3. Create a new branch: Navigate to the cloned repository directory and create a new branch for your changes:\n\n```sh\ncd commandzen\ngit checkout -b my-feature-branch\n```\n\n4. Install dependencies: Install the required dependencies for the project:\n\n```sh\nnpm install\n```\n\n5. Make your changes: Make the desired changes to the code, add new features or fix bugs. Ensure that your changes follow the existing coding style and conventions.\n\n6. Test your changes: Make sure to test your changes and ensure that all tests pass and code coverage is still at 100%:\n\n```sh\nnpm test\n```\n\n## License\n\nThis project is licensed under the MIT License.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flokicoule%2Fcommandzen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flokicoule%2Fcommandzen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flokicoule%2Fcommandzen/lists"}