{"id":21961854,"url":"https://github.com/trapcodeio/myclt","last_synced_at":"2026-05-04T10:36:52.069Z","repository":{"id":184754522,"uuid":"672404500","full_name":"trapcodeio/myclt","owner":"trapcodeio","description":"A command line Tool that provides the base for you to run and attach any programmed command. ","archived":false,"fork":false,"pushed_at":"2023-08-09T16:05:44.000Z","size":128,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"myclt","last_synced_at":"2025-03-20T05:34:54.190Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/trapcodeio.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-30T01:01:33.000Z","updated_at":"2023-09-20T13:01:24.000Z","dependencies_parsed_at":"2024-10-31T19:33:58.763Z","dependency_job_id":"47303884-972f-4684-bab0-68df4e2bf00a","html_url":"https://github.com/trapcodeio/myclt","commit_stats":{"total_commits":80,"total_committers":1,"mean_commits":80.0,"dds":0.0,"last_synced_commit":"0b45c2b2bb8fd83c79a7a49675387937684663bc"},"previous_names":["trapcodeio/ownclt","trapcodeio/myclt"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trapcodeio%2Fmyclt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trapcodeio%2Fmyclt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trapcodeio%2Fmyclt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trapcodeio%2Fmyclt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trapcodeio","download_url":"https://codeload.github.com/trapcodeio/myclt/tar.gz/refs/heads/myclt","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245017478,"owners_count":20547813,"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":[],"created_at":"2024-11-29T10:19:18.464Z","updated_at":"2026-05-04T10:36:47.036Z","avatar_url":"https://github.com/trapcodeio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MyClt\n\nIn most cases, `bash` wins when you want to create custom commands for your workflow.\nBut also in most cases, you will have to create a new file for each command and manage the files yourself.\n`bash` is also limited in what you can do with it.\n\nThis is where `myclt` comes in as a framework that sets a structure for creating commands and managing them.\nThe good side is that you can use it alongside `bash` if you want to.\nAll you have to do is create a `clt` command that runs your `bash` command.\n😁\n\n**MyClt** -\nMy command line tool is a cli framework\nfor creating custom/reusable commands.\nThe framework supports linking commands both `locally` and `remotely` from git repositories.\n\n`myclt` or `clt` is the command to run the framework. `clt` is only available if installed globally.\n\n```bash\nclt \u003cnamespace\u003e/\u003ccommand\u003e/\u003csubCommands\u003e \u003cargs\u003e\n# OR\nmyclt \u003cnamespace\u003e/\u003ccommand\u003e/\u003csubCommands\u003e \u003cargs\u003e\n```\n\n- `namespace` is the namespace of the command defined in the `myclt.map.json` file.\n- `command` is the command to run.\n- `subCommands` is the child command to run. (optional)\n- `args` is the arguments to pass to the command. (optional)\n\n\n\n##### **Menu**\n\n- [Installation](#installation)\n- [Creating commands](#creating-commands)\n    - [Javascript](#javascript)\n    - [Typescript](#typescript)\n\n## Installation\n\nNote: This package is best used if installed globally.\n\n```bash\nnpm install -g myclt\n# OR\nyarn global add myclt\n```\n\nOr using npx: (This is not recommended as it will be slow to run commands and does not support the `clt` alias)\n\n```bash\nnpx myclt \u003ccommand\u003e\n\n# For example:\nnpx myclt /list\n```\n\n## Creating commands.\n\nTo create a command, two files are needed.\n\n1. The Command file (js or ts): The file where commands are defined.\n2. The Map file (json): The file where the command is mapped to the command file.\n\n### Javascript\n\nCreate a new project and install the `myclt` package.\nThe package is needed for type definitions but not required for the command to work.\n\nCreate a command file @ `maths/index.js` with the following content:\n\n```js\nconst { defineCommands } = require(\"myclt/functions/helpers\");\n\nmodule.exports = defineCommands({\n    add({ log, args }) {\n        const [x, y] = args.map(Number);\n        log.info(`${x} + ${y} = ${x + y}`);\n    },\n    subtract({ log, args }) {\n        const [x, y] = args.map(Number);\n        log.info(`${x} - ${y} = ${x - y}`);\n    }\n});\n```\n\nCreate a map file @ `maths/myclt.map.json` with the following content:\n\n```json\n{\n  \"namespace\": \"maths\",\n  \"file\": \"./index.js\",\n  \"commands\": {\n    \"add\": {\n      \"desc\": \"Add two numbers\"\n    },\n    \"subtract\": {\n      \"desc\": \"Subtract x from y\"\n    }\n  }\n}\n```\n\nRun the command below to link the command to myclt.\n\n```bash\nclt /link maths\n```\n\nRun the command below to see the list of commands.\n\n```bash\nclt /list\n```\n\nYou should see the [maths] namespace with the commands `add` and `subtract`.\n\n### Typescript\n\n`myclt` supports typescript out of the box.\nAll you need to do is change the file extension to `.ts`.\n\n**Note:** it does not check for typescript errors, it only transpiles the file to javascript.\nYour code editor should be able to check for typescript errors or you can use `tsc` to check for errors yourself.\n\n## Command Action\n\nA command action is a function that is called when a command is run.\nThis function is passed an object with the following properties:\n\n| Property                      | Type       | Description                                                                                        |\n|-------------------------------|------------|----------------------------------------------------------------------------------------------------| \n| [`args`](#args)               | `string[]` | The arguments passed to the command.                                                               |\n| [`command`](#command)         | `string`   | The command that is currently running.                                                             |\n| [`subCommands`](#subcommands) | `string[]` | The sub commands that are currently involved.                                                      |\n| [`log`](#log)                 | `object`   | The logger instance that contains several methods for logging content to the console.              |\n| [`paths`](#paths)             | `object`   | The paths object contains all the helper properties and methods for path parsing and intelligence. |\n| [`self`](#self)               | `function` | A function that can be used to run other commands in same namespace.                               |\n| [`state`](#state)             | `class`    | An [object-collection](https://npmjs.com/package/object-collection) instance.                      |                \n| [`fromSelf`](#fromSelf)       | `boolean`  | A boolean that is true if the command was run from the same namespace.                             |\n| [`myclt`](#myclt)             | `function` | A function that returns the myclt instance.                                                        |\n| [`store`](#store)             | `object`   | A store object that contains methods for storing and retrieving persisted data.                    |\n| [`exec`](#store)              | `function` | A function for running command or multiple commands                                                |\n\n\n### `args`\nThe `args` property is an array of strings that contains the arguments passed to the command.\n\nFor example, if the command is `clt maths/add 1 2`, the `args` property will be `[\"1\", \"2\"]`.\n```ts\nfunction action({ args }) {\n    console.log(args); // [\"1\", \"2\"]\n}\n```\n\n\n### `command`\nThe `command` property is the command that is currently running.\n\nFor example, if the command is `clt maths/add 1 2`, the `command` property will be `maths/add`.\n```ts\nfunction action({ command }) {\n    console.log(command); // \"maths/add\"\n}\n```\n\n### `subCommands`\nThe `subCommands` property is an array of strings that follows the command when you split it by `/`.\n\nFor example, if the command is `clt clt/link/git/update`, `command`\nwill be `clt/link` while `subCommands` will be `[\"git\", \"update\"]`.\n```ts\nfunction action({ subCommands }) {\n    console.log(subCommands); // [\"git\", \"update\"]\n}\n```\n\n### `log`\nThe `log` property is an object that contains several methods for logging content to the console.\n\n```ts\nfunction action({ log }) {\n    log.log(\"This is a log message\");\n    log.logAndExit(\"This is a log message and the process will exit\");\n    log.success(\"This is a success message\");\n    log.successAndExit(\"This is a success message and the process will exit\");\n    log.info(\"This is an info message\");\n    log.infoAndExit(\"This is an info message and the process will exit\");\n    log.error(\"This is a warning message\");\n    log.errorAndExit(\"This is a warning message and the process will exit\");\n    log.warning(\"This is a warning message\");\n    log.warningAndExit(\"This is a warning message and the process will exit\");\n    log.emptyLine()\n}\n```\n\nNote:\nthese log functions can still be imported individually from\n`myclt/functions/loggers` if you prefer to use them that way.\n\n```ts\nimport { success, successAndExit } from \"myclt/functions/loggers\";\n\nfunction action() {\n    success(\"This is a success message\");\n    successAndExit(\"This is a success message and the process will exit\");\n}\n```\n\n### `paths`\nThe `paths` property is an object that contains all the helper properties and methods for path parsing and intelligence.\n\n#### `paths.cwd`\nThe `cwd` property is the current working directory.\n\n#### `paths.cwdResolve`\nThe `cwdResolve` property is a function that resolves a path relative to the current working directory.\n\n### `self`\nThe `self` property is a function that can be used to run other commands in same namespace.\n\nFor example:\n\n```ts\nexport default defineCommands({\n  foo({ log, self }) {\n    // call the bar command\n    log.info(\"Calling bar command\");\n    self(\"bar\");\n  },\n  bar({ log }) {\n    log.info(\"Bar command called\");\n  }\n});\n```\n### `state`\nThe `state` property is an [object-collection](https://npmjs.com/package/object-collection) instance\nthat holds the state of the command.\n\nState is only useful when you want to persist data between commands.\n\nFor example:\n\n```ts\nexport default defineCommands({\n    foo({ state, self }) {\n        state.set(\"isFoo\", true);\n        // call the bar command\n        self(\"bar\");\n    },\n    bar({ state, args }) {\n        if (state.get(\"isFoo\")) {\n            console.log(\"Foo is true\");\n        }\n    }\n});\n```\n\n### `fromSelf`\n\nThe `fromSelf` property is a boolean that is true if the command was called using a `self` function.\n\n### `myclt`\nThe `myclt` property is a function that returns the myclt instance.\n\n### `store`\nThe `store` property is an object that contains methods for storing and retrieving persisted data.\n\nThe type structure of the store object is as follows:\n\n```ts\ntype MyCltStore = {\n  set(key: string | Record\u003cstring, any\u003e, value?: any): void;\n  get\u003cT = any\u003e(key: string, def?: T): T;\n  has(key: string): boolean;\n  unset(key: string): void;\n  clear(): void;\n  commitChanges(): void;\n  collection\u003cT extends Record\u003cstring, any\u003e\u003e(): ObjectCollection\u003cT\u003e;\n};\n```\n\nSo it can be used like this:\n\n```ts\nfunction action({ store }) {\n    store.set(\"foo\", \"bar\");\n    // or\n    store.set({ foo: \"bar\" });\n    \n    store.get(\"foo\"); // \"bar\"\n    store.has(\"foo\"); // true\n    store.unset(\"foo\");\n    store.clear();\n    store.commitChanges(); // commit changes to disk\n    store.collection().all(); // get all items\n}\n```\n\n### `exec`\nThis function is just nodes `child_process.execSync` function with `stdio: \"inherit\"` option.\n```ts\nfunction action({ exec }) {\n    exec(\"npm install\");\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrapcodeio%2Fmyclt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrapcodeio%2Fmyclt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrapcodeio%2Fmyclt/lists"}