{"id":13902946,"url":"https://github.com/trvswgnr/cmdctr","last_synced_at":"2025-09-07T18:32:29.589Z","repository":{"id":215925967,"uuid":"740054490","full_name":"trvswgnr/cmdctr","owner":"trvswgnr","description":"A *tiny* no-frills library for creating CLI applications.","archived":false,"fork":false,"pushed_at":"2024-02-05T15:47:50.000Z","size":595,"stargazers_count":13,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-24T00:35:00.754Z","etag":null,"topics":["cli","commander","javascript","npm","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trvswgnr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["trvswgnr"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2024-01-07T11:45:18.000Z","updated_at":"2024-08-28T07:25:45.000Z","dependencies_parsed_at":"2024-02-05T17:05:04.540Z","dependency_job_id":null,"html_url":"https://github.com/trvswgnr/cmdctr","commit_stats":{"total_commits":68,"total_committers":2,"mean_commits":34.0,"dds":"0.11764705882352944","last_synced_commit":"b5f8d446afc9af81430caac1945e17f59cfc7361"},"previous_names":["trvswgnr/cmdctr"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trvswgnr%2Fcmdctr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trvswgnr%2Fcmdctr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trvswgnr%2Fcmdctr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trvswgnr%2Fcmdctr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trvswgnr","download_url":"https://codeload.github.com/trvswgnr/cmdctr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232242791,"owners_count":18493789,"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","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","commander","javascript","npm","terminal","typescript"],"created_at":"2024-08-06T22:01:30.954Z","updated_at":"2025-01-02T18:59:32.249Z","avatar_url":"https://github.com/trvswgnr.png","language":"TypeScript","funding_links":["https://github.com/sponsors/trvswgnr"],"categories":["cli"],"sub_categories":[],"readme":"# Command Center\n\n\u003c!-- start badges --\u003e\n[![github latest release](https://badgen.net/github/tag/trvswgnr/cmdctr?label=latest\u0026cache=600)](https://github.com/trvswgnr/cmdctr/releases/latest)\n[![npm version](https://badgen.net/npm/v/cmdctr?cache=600)](https://www.npmjs.com/package/cmdctr)\n![npm weekly downloads](https://img.shields.io/npm/dw/cmdctr)\n![dependencies](https://img.shields.io/badge/dependencies-0-orange)\n[![license](https://img.shields.io/github/license/trvswgnr/cmdctr)](LICENSE)\n[![open issues](https://badgen.net/github/open-issues/trvswgnr/cmdctr?label=issues)](https://github.com/trvswgnr/cmdctr/issues)\n[![minzipped size](https://img.shields.io/bundlephobia/minzip/cmdctr)](https://bundlephobia.com/result?p=cmdctr)\n![follow on xitter](https://img.shields.io/twitter/follow/techsavvytravvy?style=social)\n\u003c!-- end badges --\u003e\n\nCommand Center (`cmdctr`) is a [*tiny*](https://bundlephobia.com/result?p=cmdctr) no-frills library for TypeScript and JavaScript that provides a\nsimple, yet flexible way to create command line interfaces (CLI). It allows you to define commands\nwith specific options and actions, and then run these commands from the command line. Type safety is\nbuilt in, so you can be sure that your commands are being run with the correct options.\n\n\u003e [!WARNING]\n\u003e\n\u003e This project is still in early development and is not ready for production use.\n\n#### What it is\n\n`cmdctr` is a focused, streamlined tool for creating CLI apps without unnecessary complexity. It's\nheavily focused on inferred types and safety, making it ideal for rapid development. `cmdctr` is\ngreat for creating commands with specific options and actions, and executing those commands from the\ncommand line.\n\n`cmdctr` has zero external dependencies, making it lightweight and easy to include in any project.\n\n#### What it isn't\n\nYou won't find some of the cool features that often come bundled with CLI builder libraries. There\nare no color utilities, loading spinners, menus, events, or progress bars. Many established\nlibraries for those needs already exist. Instead, `cmdctr` is built to work seamlessly alongside\nthese specialized packages, allowing you to integrate only what you need.\n\n## Installation\n\n```bash\nbun i cmdctr\n# or\nnpm i cmdctr\n```\n\nOr clone the repository:\n\n```bash\ngit clone https://github.com/trvswgnr/cmdctr.git\n```\n\n## Usage\n\nCommand Center provides three main functions: `CmdCtr`, `Data`, and `Command`.\n\n### CmdCtr\n\n`CmdCtr` creates a new command center. It takes a string argument which is the name of the base\ncommand. This is the command that will be used to run commands.\n\n```ts\nimport { CmdCtr } from \"cmdctr\";\nconst cmdCtr = CmdCtr(\"example\");\n```\n\n### Data\n\n`Data` creates a new command data object. This object defines the name, description, and options for\na command.\n\n```ts\nconst command1Data = Data({\n    name: \"command-1\",\n    description: \"A command that does something\",\n    options: {\n        input: {\n            short: \"i\",\n            type: \"string\",\n            description: \"The input file to be processed\",\n            required: true,\n        },\n        output: {\n            short: \"o\",\n            type: \"string\",\n            description: \"The output file to be written\",\n            required: true,\n        },\n    },\n});\n```\n\n### Command\n\n`Command` creates a new command. It takes a data object and an action function as arguments. The\naction function is what will be executed when the command is run.\n\n```ts\nconst command1 = Command(command1Data, (opts) =\u003e {\n    const { input, output } = opts;\n    console.log(`input: ${input}`);\n    console.log(`output: ${output}`);\n});\n```\n\nA nice feature here is the options passed to the action function (`opts` here) are validated from\nthe CLI and their types are known at compile-time. This means you get meaningfull type hints and\ncode completion in your editor and can be sure that the arguments are the types you're expecting.\n\n### Registering and Running Commands\n\nAfter creating commands, you can register them to the command center using the `register` method.\nThen, you can run the commands using the `run` method.\n\n```ts\ncmdCtr.register(command1);\ncmdCtr.register(command2);\ncmdCtr.run();\n```\n\n### Setting the default command\n\nYou can set a default command to be run when no command is specified. This is done using the\n`setDefault` method.\n\n```ts\ncmdCtr.setDefault(command1);\n// or\ncmdCtr.setDefault(\"command-1\");\n```\n\n## Example\n\nHere is a complete example of how to use Command Center:\n\n```ts\n// @ts-check\nimport { CmdCtr, Data, Command } from \"cmdctr\";\nimport ora from \"ora\"; // loading spinner (for funzies)\n\nconst cmdCtr = CmdCtr(\"example\"); // or new CmdCtr(), if that's your thing\n\nconst command1Data = Data({\n    name: \"command-1\",\n    description: \"A command that does something\",\n    options: {\n        input: {\n            short: \"i\",\n            type: \"string\",\n            description: \"The input file to be processed\",\n            required: true,\n        },\n        output: {\n            short: \"o\",\n            type: \"string\",\n            description: \"The output file to be written\",\n            required: true,\n        },\n    },\n});\n\nconst command1 = Command(command1Data, (opts) =\u003e {\n    const { input, output } = opts;\n    console.log(`input: ${input}`);\n    console.log(`output: ${output}`);\n});\n\nconst command2Data = Data({\n    name: \"command-2\",\n    description: \"A command that does something else\",\n    options: {\n        message: {\n            short: \"m\",\n            type: \"string\",\n            description: \"The message to be printed\",\n            required: true,\n        },\n        loud: {\n            short: \"l\",\n            type: \"boolean\",\n            description: \"Whether the message should be printed loudly\",\n            default: false,\n        },\n    },\n});\n\nconst command2 = Command(command2Data, async (opts) =\u003e {\n    const { message, loud } = opts;\n    const loadingMsg = \"...what was i saying again?\";\n    const spinner = ora(loadingMsg).start();\n    const text = await new Promise((resolve) =\u003e {\n        setTimeout(() =\u003e resolve(`oh yeah, ${loud ? message.toUpperCase() : message}`), 2000);\n    });\n    spinner.stop();\n    console.log(text);\n});\n\ncmdCtr.register(command1);\ncmdCtr.register(command2);\ncmdCtr.setDefault(command2);\ncmdCtr.run();\n```\n\nIn this example, two commands are created: `command-1` and `command-2`. `command-1` takes an input\nfile and an output file as options, and `command-2` takes a message and a boolean flag as options.\nThe commands are then registered to the command center and run.\n\nIn this case, `command2` is registered AND set as the default command, so it will be run when no\ncommand is specified but can also be run explicitly by specifying `command-2` as the command to run.\nIf it had not been registered, it would run when no command is specified but would not be able to be\nrun explicitly as a subcommand.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Feel free to open an issue or submit a pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrvswgnr%2Fcmdctr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrvswgnr%2Fcmdctr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrvswgnr%2Fcmdctr/lists"}