{"id":17491,"library":"aedes-cli","title":"Aedes MQTT Broker CLI","description":"aedes-cli provides a command-line interface (CLI) for running an Aedes MQTT broker instance. It simplifies the deployment and configuration of an Aedes broker, allowing users to quickly set up an MQTT server with various options for host, port, protocols (TCP, TLS, WS, WSS), authentication, authorization, and persistence. The current stable version is 1.0.2. Releases are generally driven by updates to the underlying Aedes library or dependency bumps, with a focus on stability and ease of use for CLI operations. Its key differentiator is offering a batteries-included CLI wrapper around the highly customizable Aedes library, abstracting away much of the programmatic setup for common use cases.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/moscajs/aedes-cli","tags":["javascript","aedes","mqtt","broker","nodejs","cli"],"install":[{"cmd":"npm install aedes-cli","lang":"bash","label":"npm"},{"cmd":"yarn add aedes-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add aedes-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core MQTT broker functionality, aedes-cli wraps this library.","package":"aedes","optional":false},{"reason":"Used for parsing command-line arguments.","package":"yargs","optional":false}],"imports":[{"note":"Since v1.0.0, the package primarily uses ESM named exports for programmatic usage. While CommonJS `require` might work for the main CLI entry point, `start` is specifically exported as a named function.","wrong":"const { start } = require('aedes-cli');","symbol":"start","correct":"import { start } from 'aedes-cli';"},{"note":"For directly creating an Aedes broker instance programmatically via the CLI package's helper, use the named export `createBroker`. This is distinct from importing `Aedes` directly from the `aedes` package.","wrong":"import Aedes from 'aedes-cli'; Aedes.createBroker();","symbol":"createBroker","correct":"import { createBroker } from 'aedes-cli';"},{"note":"To run the CLI programmatically as if it were executed from the terminal, you might need to import a specific entry point like `aedes-cli/start`. Direct default import from 'aedes-cli' is not typically for programmatic execution of the CLI itself.","wrong":"import aedesCli from 'aedes-cli';","symbol":"default","correct":"import aedesCli from 'aedes-cli/start';"}],"quickstart":{"code":"import { start } from 'aedes-cli';\nimport { fileURLToPath } from 'url';\nimport path from 'path';\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\n\nasync function runBroker() {\n  try {\n    const options = {\n      port: 1883,\n      host: '0.0.0.0',\n      protos: ['tcp', 'ws'],\n      // Example for persistence - requires aedes-persistence-mongodb or similar\n      // persistence: path.join(__dirname, 'my-persistence-plugin.js'),\n      // Example for authorization\n      // credentials: path.join(__dirname, 'credentials.json'),\n      // authorizePublish: 'devices/+/data',\n      // authorizeSubscribe: 'devices/#',\n    };\n\n    const server = await start(options);\n\n    server.on('ready', () => {\n      console.log('Aedes MQTT Broker started successfully on port 1883 and host 0.0.0.0');\n    });\n\n    server.on('client', (client) => {\n      console.log(`Client connected: ${client.id}`);\n    });\n\n    server.on('clientDisconnect', (client) => {\n      console.log(`Client disconnected: ${client.id}`);\n    });\n\n    server.on('error', (err) => {\n      console.error('Broker error:', err.message);\n    });\n\n  } catch (error) {\n    console.error('Failed to start Aedes CLI broker:', error);\n    process.exit(1);\n  }\n}\n\nrunBroker();","lang":"typescript","description":"This code snippet demonstrates how to programmatically start the Aedes MQTT broker using `aedes-cli` with basic TCP and WebSockets protocols, and log connection events."},"warnings":[{"fix":"For programmatic usage, switch to ES Module import syntax (e.g., `import { start } from 'aedes-cli';`). Review `yargs` v18 documentation if you're interacting with its API directly within the CLI's programmatic capabilities.","message":"While `aedes-cli` v1.0.0 stated 'no breaking changes to the aedes-cli API', it significantly updated its internal dependencies, including `aedes` to v1.0.0 and `yargs` to v18. Users relying on specific versions of underlying dependencies or expecting CommonJS patterns for programmatic imports may encounter issues. Ensure your environment supports ESM for programmatic usage.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Attach an error listener to the returned server object: `server.on('error', (err) => { console.error('Broker error:', err); });` to prevent unexpected crashes.","message":"When using `aedes-cli` programmatically, the `start` function returns an Aedes server instance. It's crucial to handle errors on this server instance (e.g., `server.on('error', ...)`) as unhandled promise rejections or server errors can cause the process to exit unexpectedly. Prior versions had a 'blind catch' which was removed in 1.0.1, making error handling more explicit.","severity":"gotcha","affected_versions":">=1.0.1"},{"fix":"Use the `--host 0.0.0.0` command-line option, or set `host: '0.0.0.0'` when starting programmatically. For Docker, this is often necessary in your `docker run` command or `docker-compose.yml`.","message":"Default host for `aedes-cli` is `127.0.0.1`. If you're running it in a Docker container or want it accessible from other machines, you must explicitly set the host to `0.0.0.0`.","severity":"gotcha","affected_versions":"<=1.0.2"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Convert your project or the specific file to use ES Modules (`.mjs` extension or `\"type\": \"module\"` in `package.json`) and use `import { start } from 'aedes-cli';`.","cause":"Attempting to `require()` aedes-cli programmatically in a CommonJS context when the library or its dependencies are now primarily ES Modules.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/aedes-cli/index.js from .../my-app.js not supported."},{"fix":"Stop the conflicting process, or specify a different port for aedes-cli using the `--port <new_port>` command-line option or `{ port: <new_port> }` in programmatic options.","cause":"Another process is already listening on the specified port (1883 by default).","error":"Error: listen EADDRINUSE: address already in use 127.0.0.1:1883"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}