Aedes MQTT Broker CLI

1.0.2 verified Thu Apr 23 auth: no javascript

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.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/aedes-cli/index.js from .../my-app.js not supported. ↓

cause Attempting to `require()` aedes-cli programmatically in a CommonJS context when the library or its dependencies are now primarily ES Modules.

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';.

error Error: listen EADDRINUSE: address already in use 127.0.0.1:1883 ↓

cause Another process is already listening on the specified port (1883 by default).

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.

Warnings

breaking 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. ↓

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.

gotcha 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. ↓

fix Attach an error listener to the returned server object: `server.on('error', (err) => { console.error('Broker error:', err); });` to prevent unexpected crashes.

gotcha 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`. ↓

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`.

Install

npm install aedes-cli

yarn add aedes-cli

pnpm add aedes-cli

Imports

start
wrong
```
const { start } = require('aedes-cli');
```
correct
```
import { start } from 'aedes-cli';
```
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.
createBroker
wrong
```
import Aedes from 'aedes-cli'; Aedes.createBroker();
```
correct
```
import { createBroker } from 'aedes-cli';
```
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.
default
wrong
```
import aedesCli from 'aedes-cli';
```
correct
```
import aedesCli from 'aedes-cli/start';
```
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.

Quickstart

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.

import { start } from 'aedes-cli';
import { fileURLToPath } from 'url';
import path from 'path';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

async function runBroker() {
  try {
    const options = {
      port: 1883,
      host: '0.0.0.0',
      protos: ['tcp', 'ws'],
      // Example for persistence - requires aedes-persistence-mongodb or similar
      // persistence: path.join(__dirname, 'my-persistence-plugin.js'),
      // Example for authorization
      // credentials: path.join(__dirname, 'credentials.json'),
      // authorizePublish: 'devices/+/data',
      // authorizeSubscribe: 'devices/#',
    };

    const server = await start(options);

    server.on('ready', () => {
      console.log('Aedes MQTT Broker started successfully on port 1883 and host 0.0.0.0');
    });

    server.on('client', (client) => {
      console.log(`Client connected: ${client.id}`);
    });

    server.on('clientDisconnect', (client) => {
      console.log(`Client disconnected: ${client.id}`);
    });

    server.on('error', (err) => {
      console.error('Broker error:', err.message);
    });

  } catch (error) {
    console.error('Failed to start Aedes CLI broker:', error);
    process.exit(1);
  }
}

runBroker();