{"id":20738924,"url":"https://github.com/moscajs/aedes-cli","last_synced_at":"2025-04-08T03:08:46.938Z","repository":{"id":41759402,"uuid":"235808913","full_name":"moscajs/aedes-cli","owner":"moscajs","description":"Run Aedes MQTT Broker from the CLI","archived":false,"fork":false,"pushed_at":"2025-03-10T22:28:06.000Z","size":2291,"stargazers_count":56,"open_issues_count":11,"forks_count":19,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-31T21:42:46.595Z","etag":null,"topics":["aedes","broker","cli","hacktoberfest","mqtt","nodejs"],"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/moscajs.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":"robertsLando","patreon":"user?u=16906849","custom":["paypal.me/daniellando","https://www.amazon.it/hz/wishlist/ls/2LYWFKB0WTSNN?ref_=wl_share"]}},"created_at":"2020-01-23T14:14:27.000Z","updated_at":"2025-02-22T03:27:49.000Z","dependencies_parsed_at":"2024-07-30T09:42:54.627Z","dependency_job_id":null,"html_url":"https://github.com/moscajs/aedes-cli","commit_stats":{"total_commits":172,"total_committers":9,"mean_commits":19.11111111111111,"dds":0.5406976744186047,"last_synced_commit":"9f6485c0b2cef3c1195f0388fe85f8cb0ee1e524"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moscajs%2Faedes-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moscajs%2Faedes-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moscajs%2Faedes-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moscajs%2Faedes-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moscajs","download_url":"https://codeload.github.com/moscajs/aedes-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247767234,"owners_count":20992547,"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":["aedes","broker","cli","hacktoberfest","mqtt","nodejs"],"created_at":"2024-11-17T06:21:38.603Z","updated_at":"2025-04-08T03:08:46.916Z","avatar_url":"https://github.com/moscajs.png","language":"JavaScript","funding_links":["https://github.com/sponsors/robertsLando","https://patreon.com/user?u=16906849","paypal.me/daniellando","https://www.amazon.it/hz/wishlist/ls/2LYWFKB0WTSNN?ref_=wl_share","https://www.buymeacoffee.com/MVg9wc2HE","https://paypal.me/daniellando","https://www.patreon.com/bePatron?u=16906849"],"categories":[],"sub_categories":[],"readme":"# aedes-cli\n\n![CI](https://github.com/moscajs/aedes-cli/workflows/CI/badge.svg)\n![Docker Build](https://github.com/moscajs/aedes-cli/workflows/Docker%20Build/badge.svg)\n[![Total alerts](https://img.shields.io/lgtm/alerts/g/moscajs/aedes-cli.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/moscajs/aedes-cli/alerts/)\n[![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/moscajs/aedes-cli.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/moscajs/aedes-cli/context:javascript)\n[![NPM version](https://img.shields.io/npm/v/aedes-cli.svg?style=flat)](https://www.npmjs.com/aedes-cli)\n[![NPM downloads](https://img.shields.io/npm/dm/aedes-cli.svg?style=flat)](https://www.npmjs.com/aedes-cli)\n[![Known Vulnerabilities](https://snyk.io/test/github/moscajs/aedes-cli/badge.svg?targetFile=package.json)](https://snyk.io/test/github/moscajs/aedes-cli?targetFile=package.json)\n\n[![Buy Me A Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/MVg9wc2HE \"Buy Me A Coffee\") [\u003cimg style=\"background:#ccc;border-radius:10px\" alt=\"PayPal\" src=\"https://www.paypalobjects.com/paypal-ui/logos/svg/paypal-color.svg\" alt=\"PayPal\" width=\"200\" height=\"40px\" /\u003e](https://paypal.me/daniellando) [![Patreon](https://c5.patreon.com/external/logo/become_a_patron_button.png)](https://www.patreon.com/bePatron?u=16906849)\n\n[Aedes](https://github.com/moscajs/aedes) MQTT broker CLI plugin\n\n- [aedes-cli](#aedes-cli)\n  - [Install](#install)\n  - [Usage](#usage)\n  - [Programmatically](#programmatically)\n  - [Docker](#docker)\n  - [Authorization](#authorization)\n  - [Persistence and Emitters](#persistence-and-emitters)\n\n## Install\n\nInstall the library using [npm](http://npmjs.org/).\n\n```bash\nnpm install aedes-cli -g\n```\n\n## Usage\n\nHere you can see the options accepted by the command line tool:\n\n```text\n$ aedes -h\n\n ______   ________  _______   ________   ______  \n/      \\ |        \\|       \\ |        \\ /      \\\n|  $$$$$$\\| $$$$$$$$| $$$$$$$\\| $$$$$$$$|  $$$$$$\\\n| $$__| $$| $$__    | $$  | $$| $$__    | $$___\\$$\n| $$    $$| $$  \\   | $$  | $$| $$  \\    \\$$    \\\n| $$$$$$$$| $$$$$   | $$  | $$| $$$$$    _\\$$$$$$\\\n| $$  | $$| $$_____ | $$__/ $$| $$_____ |  \\__| $$\n| $$  | $$| $$     \\| $$    $$| $$     \\ \\$$    $$\n\\$$   \\$$ \\$$$$$$$$ \\$$$$$$$  \\$$$$$$$$  \\$$$$$$\n\nUsage: aedes [command] [options]\n\nCommands:\n  aedes adduser \u003cuser\u003e \u003cpassword\u003e  Add a user to given credentials file\n  aedes rmuser \u003cuser\u003e              Removes a user from given credentials file\n  aedes start                      Starts Aedes broker with given options\n                                                                       [default]\n\nOptions:\n  --port, -p             the port to listent to         [number] [default: 1883]\n  --host                 the host to listen to   [string] [default: \"127.0.0.1\"]\n  --protos               protocols to use\n                 [array] [choices: \"tcp\", \"tls\", \"ws\", \"wss\"] [default: [\"tcp\"]]\n  --credentials          \u003cfile\u003e the file containing the credentials     [string]\n  --authorize-publish    \u003cpattern\u003e the pattern for publishing to topics for the\n                         added user                                     [string]\n  --authorize-subscribe  \u003cpattern\u003e the pattern for subscribing to topics for the\n                         added user                                     [string]\n  --concurrency          broker maximum number of concurrent messages delivered\n                         by mqemitter                    [number] [default: 100]\n  --queueLimit           broker maximum number of queued messages before client\n                         session is established           [number] [default: 42]\n  --maxClientsIdLength   broker option to override MQTT 3.1.0 clients Id length\n                         limit                            [number] [default: 23]\n  --heartbeatInterval    interval in millisconds at which broker beats its\n                         health signal in $SYS/\u003cbroker.id\u003e/heartbeat\n                                                       [number] [default: 60000]\n  --connectTimeout       maximum waiting time in milliseconds waiting for a\n                         CONNECT packet                [number] [default: 30000]\n  --key                  \u003cfile\u003e the server's private key                [string]\n  --cert                 \u003cfile\u003e the certificate issued to the server    [string]\n  --reject-unauthorized  reject clients using self signed certificates\n                                                       [boolean] [default: true]\n  --tls-port             the TLS port to listen to      [number] [default: 8883]\n  --ws-port              mqtt-over-websocket server port[number] [default: 3000]\n  --wss-port             mqtt-over-secure-websocket server port\n                                                        [number] [default: 4000]\n  --stats                enable publish of stats under $SYS\n                                                      [boolean] [default: false]\n  --stats-interval       interval between aedes stats pubs\n                                                        [number] [default: 5000]\n  --broker-id            the id of the broker in the $SYS/\u003cid\u003e namespace\n                                                 [string] [default: \"aedes-cli\"]\n  --config, -c           \u003cfile\u003e the config file to use (overrides every other\n                         option)                                        [string]\n  --verbose, -v          set the log level to INFO    [boolean] [default: false]\n  --very-verbose         set the log level to DEBUG   [boolean] [default: false]\n  --no-pretty            JSON logs                    [boolean] [default: false]\n  -V, --version          Show version number                           [boolean]\n  -h, --help             Show help                                     [boolean]\n\nExamples:\n  aedes --protos tcp ws                     Starts Aedes broker with TCP and WS\n                                            servers\n  aedes --config myConfig.js                Starts Aedes broker with custom\n                                            config file\n  aedes --stats -v --statsInterval 2000     Starts Aedes broker with stats\n                                            enabled\n  aedes --credentials ./credentials.json    Add/Modify user1 with password1 to\n  adduser user1 password1                   credentials\n  aedes --credentials ./credentials.json    Removes user1 from credentials\n  rmuser user1\n```\n\nTo fully use Aedes you need to define a configuration file where the communication\nbroker is defined. Here follows an example using Mongodb.\n\nA configuration file is structured in the following way:\n\n```js\nmodule.exports = {\n  protos: ['tcp'],\n  host: '0.0.0.0',\n  port: 1883,\n  wsPort: 3000,\n  wssPort: 4000,\n  tlsPort: 8883,\n  brokerId: 'aedes-cli',\n  credentials: './credentials.json',\n  persistence: {\n    name: 'mongodb',\n    options: {\n      url: 'mongodb://127.0.0.1/aedes'\n    }\n  },\n  mq: {\n    name: 'mongodb',\n    options: {\n      url: 'mongodb://127.0.0.1/aedes'\n    }\n  },\n  key: null,\n  cert: null,\n  rejectUnauthorized: true,\n  verbose: false,\n  veryVerbose: false,\n  noPretty: false\n}\n\n```\n\n## Programmatically\n\nYou can also use `aedes-cli` programmatically:\n\n```js\nconst { start, adduser, rmuser } = require('aedes-cli')\n\nstart({\n  protos: ['tcp'],\n})\n```\n\n## Docker\n\n`aedes-cli` is available on [Docker-Hub](https://hub.docker.com/r/moscajs/aedes) for `amd64, arm64v8, arm32v6, arm32v7, i386` archs. If you want to use a local `credentials.json` file and/or a custom config file to pass using `--config` option you have to use docker volumes and map the local folder containing those files to a folder inside the container.\n\nMinimal example:\n\n`docker run --rm -it -p 1883:1883 moscajs/aedes:latest`\n\nExample with custom config file:\n\n`docker run --rm -it -p 1883:1883 -v $(pwd):/data moscajs/aedes:latest --config /data/myConfig.js`\n\n- `-v $(pwd):/data` will map the local folder from where you are running this command to `/data` folder of the container\n- `--config /data/myConfig.js` will tell aedes to use the configuration file that is in your local folder\n\n[Here](/docker/docker-compose.yml) there is an example with `docker-compose` that runs aedes with `mongodb` as persistence\n\n ```yml\n version: '3.7'\nservices:\n  aedes:\n    container_name: aedes\n    image: moscajs/aedes:latest\n    restart: always\n    stop_signal: SIGINT\n    networks:\n      - mqtt\n    command: --config /data/mongodbConfig.js # add here the options to pass to aedes\n    volumes:\n      - ./:/data # map the local folder to aedes\n    ports:\n      - '1883:1883'\n      - '3000:3000'\n      - '4000:4000'\n      - '8883:8883'\n  mongo:\n    container_name: mongo\n    networks:\n      - mqtt\n    logging:\n      driver: none\n    image: mvertes/alpine-mongo\n    volumes:\n      - db-data:/data/db\n    ports:\n      - \"27017:27017\"\nvolumes:\n  db-data:\n    name: db-data\nnetworks:\n  mqtt:\n ```\n\n When using persistences with docker-compose file remember that the database url will be the name of the service in docker-compose, in the mongo example it will be: `mongodb://mongo/dbName`.\n\n## Authorization\n\nAedes supports user authentication through the use of a specific json file.\nIn order to create one run the following command.\n\n```bash\n// add a user\n$ aedes adduser \u003cuser\u003e \u003cpass\u003e --credentials ./credentials.json\n\n// add a user specifying the authorized topics\n$ aedes adduser myuser mypass --credentials ./credentials.json \\\n  --authorize-publish 'hello/*' --authorize-subscribe 'hello/*'\n\n// remove a user\n$ aedes rmuser myuser --credentials ./credentials.json\n\n// start aedes with a specific set of credentials:\n$ aedes --credentials ./credentials.json\n```\n\nThe patterns are checked and validated using [Minimatch](https://github.com/isaacs/minimatch).\nThe credentials file is automatically reloaded by aedes when it receives a `SIGHUP`.\n\n## Persistence and Emitters\n\nThe MQTT specification requires a persistent storage for offline QoS 1\nsubscription that has been done by an unclean client. Aedes offers several\npersitance options.\n\nSupported persistences are:\n\n- [aedes-persistence]: In-memory implementation of an Aedes persistence\n- [aedes-persistence-mongodb]: MongoDB persistence for Aedes\n- [aedes-persistence-redis]: Redis persistence for Aedes\n\nEmitters are needed to deliver messages to subscribed clients. In a cluster environment it is used also to share messages between brokers instances\n\nAll of them can be configured from the configuration file, under the `persistence` and `mq` key.\n\nSupported mqemitters are:\n\n- [mqemitter]: An opinionated memory Message Queue with an emitter-style API\n- [mqemitter-redis]: Redis-powered mqemitter\n- [mqemitter-mongodb]: Mongodb based mqemitter\n\n[aedes-persistence]: https://www.npmjs.com/aedes-persistence\n[aedes-persistence-mongodb]: https://www.npmjs.com/aedes-persistence-mongodb\n[aedes-persistence-redis]: https://www.npmjs.com/aedes-persistence-redis\n\n[mqemitter]: https://www.npmjs.com/mqemitter\n[mqemitter-redis]: https://www.npmjs.com/mqemitter-redis\n[mqemitter-mongodb]: https://www.npmjs.com/mqemitter-mongodb\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoscajs%2Faedes-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoscajs%2Faedes-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoscajs%2Faedes-cli/lists"}