{"id":22199614,"url":"https://github.com/hellocomet/greytape","last_synced_at":"2025-07-27T02:32:07.937Z","repository":{"id":57254018,"uuid":"112876509","full_name":"hellocomet/greytape","owner":"hellocomet","description":"A node library to create command line tools from shell commands","archived":false,"fork":false,"pushed_at":"2018-06-19T08:07:04.000Z","size":32,"stargazers_count":6,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-16T01:25:28.571Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/hellocomet.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}},"created_at":"2017-12-02T21:01:23.000Z","updated_at":"2020-08-09T19:35:41.000Z","dependencies_parsed_at":"2022-08-31T09:01:56.262Z","dependency_job_id":null,"html_url":"https://github.com/hellocomet/greytape","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellocomet%2Fgreytape","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellocomet%2Fgreytape/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellocomet%2Fgreytape/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellocomet%2Fgreytape/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hellocomet","download_url":"https://codeload.github.com/hellocomet/greytape/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227750186,"owners_count":17814129,"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-12-02T15:15:53.520Z","updated_at":"2024-12-02T15:15:56.231Z","avatar_url":"https://github.com/hellocomet.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Greytape\n\nGreytape is a [Node.js](https://nodejs.org) library to create custom command line tools from shell commands. The original use case was to create helpers for a Docker development environment, but really anything that can be done in a shell can be integrated as a greytape command.\n\n## Installation\n\nSimply install `greytape` with `npm`...\n\n```\nnpm install --save greytape\n```\n\n... and require it in your script :\n\n```javascript\nconst greytape = require('greytape')\n```\n\n## Basic usage\n\nAt its simplest, greytape allows you to map your tool's commands to actual shell commands. Let's say you want to create an application named `cli` to manage your docker containers. `cli` could be used like this :\n\n```\n# cli up\n// executes docker-compose up\n# cli down\n// docker-compose down\n# cli api ssh\n// ssh into the api container\n# cli frontend build\n// builds the frontend\n```\nWith greytape, this would look like :\n\n```javascript\nconst greytape = require('greytape')\n\n// The configuration is passed as an object to greytape\ngreytape({\n  // The __core block contains the commands that don't have a prefix\n  __core: {\n    up: { commands: 'docker-compose up' },\n    down: { commands: 'docker-compose down' },\n  },\n  // The api prefix\n  api: {\n    ssh: { commands: 'docker exec -it api_container /bin/bash' }\n  },\n  // The frontend prefix\n  frontend: {\n  \t// commands can be supplied as an array, they are executed sequentially and synchronously\n    build: { commands: ['cd ./frontend', 'npm run build'] }\n  }\n})\n```\n\n## Advanced usage\n\n(See [API Reference](API.md) for complete instructions)\n\n### Arguments management\n\nGreytape commands can handle arguments. You can specify defaults, and even manipulate the arguments before they are sent to the shell commands.\n\nAt minimum, you need to provide :\n- `options` : an array of parameter names\n- `commands` : instead of a string or array of strings, `commands` can be a function. It will be executed with the options provided by the user, and must return a string or an array of strings.\n\n```javascript\ngreytape({\n  __core: {\n    data: {\n      options: ['database'],\n      commands: options =\u003e `psql -d ${options.database}`\n    }\n  },\n})\n\n```\n\nSee [the API reference](API.md#arguments-management) for advanced instructions.\n\n### Taking the user to a different shell\n\nBecause greytape pipes stdin \u0026 stdout to the commands, you can take the user to a different shell, for example by connecting to a server with `ssh`, or by using any REPL like `node` or `psql` (see [previous example](#arguments-management)).\n\nDoing this blocks the execution, so if you have provided an array of commands the next one won't execute until this process ends (for example when the user quits the shell).\n\n### Executing commands in containers\n\nFor each greytape command, you can specify a Docker container name with the `inContainer` option. The command is executed inside the container by wrapping it with `docker exec -it \u003ccontainer\u003e /bin/bash -c \u003ccommand\u003e`.\n\n```javascript\ngreytape({\n  data: {\n    explore: {\n      inContainer: 'db_container_1',\n      commands: 'psql -d apidata'\n    }\n  }\n})\n```\n\n### Configuration management\n\nFor the moment, the only configuration option available is `cwd`, which indicates the directory in which all commands will be executed. (Don't hesitate and just [raise an issue](https://github.com/hellocomet/greytape/issues) if you need other configuration options :) )\n\nGreytape handles the configuration with a dotfile, located in your home folder, and named after the `__root` of your application (in our example, `~/.cli.json`). See [the API reference](API.md#__cwd) for more details.\n\n\n## Self-documentation\n\nGreytape can generate the documentation of your application if you provide a `__root` option, indicating the name of the application, and if your commands have hints indicating what they do.\n\nLet's add some documentation to our `cli` application :\n\n```javascript\nconst greytape = require('greytape')\n\ngreytape({\n  // The application's name\n  __root: 'cli',\n  __core: {\n    up: {\n      // The hint for the up command\n      hint: 'Starts the containers',\n      commands: 'docker-compose up'\n    },\n    down: {\n      hint: 'Stops the containers',\n      commands: 'docker-compose down'\n    },\n    data: {\n      hint: \"Connect to a database\",\n      options: ['database'],\n      commands: options =\u003e `psql -d ${options.database}`\n    }\n  },\n  // The api prefix\n  api: {\n    ssh: {\n      hint: 'SSH into the API container',\n      commands: 'docker exec -it api_container /bin/bash'\n    }\n  }\n  // The frontend prefix\n  frontend: {\n    build: {\n      hint: 'Build the frontend with webpack',\n      commands: ['cd ./frontend', 'npm run build']\n    }\n  }\n})\n```\n\nThe documentation can be accessed by calling `cli` with no arguments, or with `-h`, `--help` or `help`.\n\n```\n# cli -h\n- Core commands\ncli up : Starts the containers\ncli down : Stops the containers\ncli data [database] : Connect to a database\n- api commands\ncli api ssh : SSH into the API container\n- frontend commands\ncli frontend build : Build the frontend with webpack\n```\n\n## Installing your application\n\nYou can call a greytape application with `node cli.js command arguments` but in most cases you will want your application to be installed globally.\n\nYou simply need to add a `bin` section to your `package.json`, specifying the binary's name and the js file that should be executed :\n\n```json\n{\n  \"name\": \"cli\",\n  \"version\": \"1.0.0\",\n  \"description\": \"An example CLI application made with greytape.js\",\n  \"bin\": {\n    \"cli\": \"index.js\"\n  },\n  \"author\": \"Damien BUTY\",\n  \"license\": \"MIT\",\n  \"dependencies\": {\n    \"greytape\": \"^0.5.0\"\n  }\n}\n```\n\nThen go to your application's folder and `npm install -g` (you will probably need `sudo` privileges).\n\nThis makes the application accessible from anywhere in your system by creating a symlink in a folder of your PATH (in general `/usr/bin`).\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhellocomet%2Fgreytape","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhellocomet%2Fgreytape","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhellocomet%2Fgreytape/lists"}