{"id":13903046,"url":"https://github.com/d4rkr00t/opaline","last_synced_at":"2025-03-04T22:48:13.292Z","repository":{"id":42209542,"uuid":"183192087","full_name":"d4rkr00t/opaline","owner":"d4rkr00t","description":"NextJS for CLI tools","archived":false,"fork":false,"pushed_at":"2023-01-07T04:08:50.000Z","size":2283,"stargazers_count":94,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-04T19:42:50.483Z","etag":null,"topics":["cli","command-line","command-line-tool","framework","javascript"],"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/d4rkr00t.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}},"created_at":"2019-04-24T09:10:39.000Z","updated_at":"2024-03-07T19:16:45.000Z","dependencies_parsed_at":"2023-02-06T11:15:47.275Z","dependency_job_id":null,"html_url":"https://github.com/d4rkr00t/opaline","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d4rkr00t%2Fopaline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d4rkr00t%2Fopaline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d4rkr00t%2Fopaline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d4rkr00t%2Fopaline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/d4rkr00t","download_url":"https://codeload.github.com/d4rkr00t/opaline/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241935237,"owners_count":20044826,"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","command-line","command-line-tool","framework","javascript"],"created_at":"2024-08-06T22:01:35.251Z","updated_at":"2025-03-04T22:48:13.268Z","avatar_url":"https://github.com/d4rkr00t.png","language":"TypeScript","funding_links":[],"categories":["cli"],"sub_categories":[],"readme":"\u003cbr/\u003e\n\u003cbr/\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"/assets/opaline.png\" alt=\"opaline\" width=\"340\" align=\"center\"\u003e\n\u003c/div\u003e\n\u003cbr/\u003e\n\u003cbr/\u003e\n\u003ch2 align=\"center\"\u003eOpaline – CLI Tools Framework\u003c/h2\u003e\n\u003cbr/\u003e\n\n![Node.js CI](https://github.com/d4rkr00t/opaline/workflows/Node.js%20CI/badge.svg)\n\n**Opaline** — a CLI tools framework and compiler. It draws inspiration from [NextJS](https://nextjs.org/)(and similar projects) and provides a quick, convention based, way of creating CLI tools.\n\n1. It looks for files in `./commands` folder and treats them as commands for a CLI:\n\n   - ```\n     commands\n     └── build.ts\n\n     # Means it can be run as following:\n     λ cli build\n     ```\n\n2. Command file must export a function (can be async function too):\n   - ```js\n     export default function myCommand() {}\n     // or\n     module.exports = async function myCommand() {};\n     ```\n3. Uses JSDoc to describe parameters and documentation for a CLI. Read more on supported JSDoc syntax and how to use it [here](#jsdoc).\n\n## Table of Contents\n\n- [Table of Contents](#table-of-contents)\n- [Usage](#usage)\n- [Creating Commands](#creating-commands)\n  - [Adding Command Parameters and Documentation](#adding-command-parameters-and-documentation)\n    - [Using unnamed arguments](#using-unnamed-arguments)\n- [JSDoc](#jsdoc)\n  - [Supported JSDoc Tags](#supported-jsdoc-tags)\n  - [Extra JSDoc Tags](#extra-jsdoc-tags)\n- [package.json](#packagejson)\n  - [package.json#bin](#packagejsonbin)\n  - [package.json#description](#packagejsondescription)\n- [Examples](#examples)\n- [Screenshots](#screenshots)\n\n## Usage\n\nUse a generator to bootstrap an **Opaline** based CLI:\n\n```sh\nλ npx @opaline/core create app\nλ cd app\nλ npm install\n```\n\nCompile the CLI:\n\n```sh\nλ npm run build\nλ npm run dev # for dev mode with watch and auto linking\n```\n\n## Creating Commands\n\nBy default generator creates `commands/index.js` file, which is a default command, and can be run without specifying a command name:\n\n```\nλ cli --param1 20\n```\n\nBut if required there might be multiple commands in one CLI. In order to do that, we just need to create another file in `./commands` folder (or rename `index.js`, it's not required to have a default command):\n\n```js\n// ./commands/build.js\n\nexport default function build() {\n  console.log(\"hello build!\");\n}\n```\n\n### Adding Command Parameters and Documentation\n\nOpaline uses JSDoc to define parameters and documentation for a command.\n\n#### Using unnamed arguments\n\nOpaline can pass all non-flag arguments to a command, for this command needs to define an `$inputs` argument in the JSDoc as shown below:\n\n```js\n// ./commands/build.js\n/**\n * Description of a command is just a comment above the command's function.\n * Params are described as JSDoc params:\n *\n * @param {Array\u003cstring\u003e} $inputs Any non-flag arguments are passed here\n */\nexport default function build($inputs) {\n  console.log(`hello ${name}, language ${lang}`);\n}\n```\n\nIt's also possible to define named (flag) arguments:\n\n```js\n// ./commands/build.js\n\n/**\n * Description of a command is just a comment above the command's function.\n * Params are described as JSDoc params:\n *\n * @param {Array\u003cstring\u003e} $input Any non-flag arguments are passed here\n * @param {string} name Name of an app to build\n * @param {string} [lang=\"TypeScript\"] A parameter with default value\n */\nexport default function build($inputs, name, lang) {\n  console.log(`hello ${name}, language ${lang}`);\n}\n```\n\nHelp will be generated for both default and this new command:\n\n```\nλ examples-for-docs --help # help for the whole cli, with list of commands\n\nVERSION\n  examples-for-docs/0.0.0\n\nUSAGE\n  examples-for-docs inputs --param1 10 --param2 20\n\nCOMMANDS\n  build     Description of a command is just a comment above the command's function. Params are described as JSDoc params:\n\n\u003e NOTE: To view the usage information for a specific command, run 'examples-for-docs [COMMAND] --help'\n\nOPTIONS\n  --param1      Some parameter for a CLI with a default value [number] [default: 20]\n  --param2      Some parameter for a CLI [string]\n  --help        Output usage information\n  --version     Output the version number\n\n\n\n\nλ examples-for-docs build --help # help for a subcommand\n\nDescription of a command is just a comment above the command's function. Params are described as JSDoc params:\n\nOPTIONS\n  --name     Name of an app to build [string]\n  --lang     A parameter with default value [string] [default: \"TypeScript\"]\n```\n\n## JSDoc\n\n\u003e **Opaline** uses JSDoc to describe command's parameters and documentation.\n\n### Supported JSDoc Tags\n\n| Tag                                          | Description                                                                               |\n| -------------------------------------------- | ----------------------------------------------------------------------------------------- |\n| `@param` – https://jsdoc.app/tags-param.html | Supports primitive types: `string`, `number`, `boolean`. And arrays of strings `string[]` |\n| `@example`                                   | **Note: only one line examples**: `@example {cliName} --params 10`                        |\n\n### Extra JSDoc Tags\n\n| Tag              | Description                                                                                                                  |\n| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| `@param $inputs` | Indicates that command receives unnamed arguments                                                                            |\n| `@usage`         | Similar to example, but outlines the main example on how to use a CLI command. `@usage {cliName} build`                      |\n| `@short`         | Defines an alias (shortcut) for a parameter. `@short name=n`                                                                 |\n| `{cliName}`      | A variable that will be replaced by the name of a CLI tool described in `package.json`. Supported by `@usage` and `@example` |\n\n## package.json\n\nOpaline gets multiple things from a `package.json` file, to even more reduce configuration:\n\n### package.json#bin\n\nhttps://docs.npmjs.com/files/package.json#bin\n\nThere are 2 way of using the `bin` field in `package.json`:\n\n```js\n// 1\n{\n  \"name\": \"cli-name\",\n  \"bin\": \"./cli/cli.js\"\n}\n\n// 2\n{\n  \"name\": \"cli-name\",\n  \"bin\": {\n    \"cli-name\": \"./cli/cli.js\"\n  }\n}\n```\n\n**Opaline** supports both of them. And uses those fields in a following way:\n\n1. Path to a CLI file – For both cases the file path is used as an output target for a CLI entry point, **and will be automatically created by Opaline, no need to manually create it.**\n2. Name of a CLI – For [1] the name will be `package.json#name`, if you need to have a different name than the name of a package, use an option 2. Name is used as `{cliName}` in JSDoc and also when linking packages in dev mode. Which makes them accessible globally, by this name:\n   - `cli-name [COMMAND]`\n\n### package.json#description\n\nUsed as main description for a CLI tool.\n\n## Examples\n\nTools built with **Opaline**:\n\n- [Opaline CLI itself](https://github.com/d4rkr00t/opaline/tree/master/packages/core/commands)\n- [Example Choose Reviewer Tool](https://github.com/d4rkr00t/review-tools)\n- [Using JSX and Ink](examples/ink/)\n  - [Ink](https://github.com/vadimdemedes/ink)\n\n## Screenshots\n\n![](assets/screenshots/build.png)\n\n![](assets/screenshots/dev-mode.png)\n\n![](assets/screenshots/help.png)\n\n![](assets/screenshots/subcommand-help.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd4rkr00t%2Fopaline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd4rkr00t%2Fopaline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd4rkr00t%2Fopaline/lists"}