HiveMQ MQTT CLI: prueba cualquier broker desde la terminal

La HiveMQ MQTT CLI (mqtt-cli) es un cliente de línea de comandos de código abierto, basado en Java, que funciona con cualquier broker MQTT. Su comando es simplemente mqtt, y cuatro subcomandos cubren casi cualquier prueba desde la terminal: mqtt pub, mqtt sub, la shell interactiva mqtt shell y mqtt test, que analiza lo que soporta un broker.

Esta guía muestra cómo instalarla, conectarte a un broker real con TLS y credenciales, usar propiedades de MQTT 5 y ejecutar el test de funciones, con comandos listos para copiar.

Instalar mqtt-cli

Las versiones recientes también incluyen binarios nativos, así que Java no siempre es necesario. Comprueba la instalación con mqtt --version. Con Docker, el entry point de la imagen es la CLI, de modo que docker run --rm -it hivemq/mqtt-cli pub -h ... sustituye a mqtt pub -h ....

Publicar y suscribirse

Abre dos terminales. Inicia primero el suscriptor para que esté escuchando cuando llegue el mensaje:

mqtt sub -h broker.connectmq.com -p 1883 \
  -t 'testmqtt/cli/#' -q 1 -T

mqtt pub -h broker.connectmq.com -p 1883 \
  -t 'testmqtt/cli/hello' -m 'Hello from mqtt-cli' -q 1

-T (--showTopics) imprime el topic antes de cada payload, algo necesario al suscribirse con wildcards. Las opciones que más usarás:

Dos flags del suscriptor son útiles en scripts: -J (--jsonOutput) imprime cada mensaje como un objeto JSON con topic, QoS y payload, y -of messages.log (--outputToFile) lo añade todo a un archivo. Pasa el JSON por jq y tendrás una herramienta rápida de aserciones.

Credenciales y TLS

mqtt pub -h broker.connectmq.com -p 8883 -s \
  -u "$MQTT_USER" -pw "$MQTT_PASS" \
  -t 'testmqtt/cli/secure' -m 'over TLS'

-s (--secure) activa TLS con el almacén de confianza del sistema. Para un broker con CA privada añade --cafile ca.pem; para TLS mutuo añade --cert client.pem --key client.key. Un handshake fallido imprime una excepción SSL de Java: consulta probar la conexión TLS para aislar primero los problemas de certificados con openssl.

WebSocket

Las apps de navegador llegan al broker por WebSocket, y a veces los proxies rompen justo ese camino. Pruébalo directamente:

mqtt sub -h broker.connectmq.com -p 8084 -s \
  -ws -ws:path /mqtt \
  -t 'testmqtt/cli/#' -T

Si esto funciona pero tu app web no, el problema está en el navegador (contenido mixto, CORS, URL incorrecta), no en el broker.

Propiedades de MQTT 5

mqtt pub expone las propiedades del PUBLISH de MQTT 5 como flags, lo que resulta práctico para comprobar que un broker las reenvía:

mqtt pub -h broker.connectmq.com -p 1883 \
  -t 'testmqtt/cli/props' -m '{"cmd":"reboot"}' -q 1 \
  -up 'source=ci' -up 'trace-id=abc123' \
  -ct application/json \
  -e 60 \
  -rt 'testmqtt/cli/replies' -cd 'req-42'

Esto define dos user properties, un content type, un message expiry de 60 segundos, un response topic y correlation data. Ejecuta el suscriptor con -J y las propiedades aparecerán en su salida. La guía de pruebas de funciones de MQTT 5 explica qué debe hacer cada propiedad y cómo verificarlo.

La shell interactiva

mqtt shell inicia un REPL en el que puedes mantener varios clientes conectados a la vez y cambiar entre ellos: perfecto para reproducir interacciones como la toma de sesión o las suscripciones no-local sin abrir cinco terminales.

mqtt> con -i sensor-1 -h broker.connectmq.com -p 1883
sensor-1@broker.connectmq.com> sub -t testmqtt/cli/commands -q 1
sensor-1@broker.connectmq.com> con -i backend-1 -h broker.connectmq.com -p 1883
backend-1@broker.connectmq.com> pub -t testmqtt/cli/commands -m 'restart'
backend-1@broker.connectmq.com> switch sensor-1
sensor-1@broker.connectmq.com> ls
sensor-1@broker.connectmq.com> dis
mqtt> exit

con conecta un cliente nuevo y lo convierte en el contexto activo; pub, sub y unsub actúan sobre el cliente activo; switch cambia de contexto; ls lista los clientes conectados; dis desconecta. Los mensajes que recibe un cliente suscrito se imprimen en la shell a medida que llegan. Un experimento rápido: conecta un segundo cliente con el mismo -i sensor-1 y verás cómo el primero se desconecta, el síntoma clásico de un client ID duplicado.

mqtt test: averigua qué soporta el broker

mqtt test se conecta a un broker e informa de qué funciones de MQTT operan. Es la forma más rápida de responder a «¿este broker soporta MQTT 5, QoS 2, mensajes retenidos y suscripciones compartidas?».

mqtt test -h broker.connectmq.com -p 1883 -u "$MQTT_USER" -pw "$MQTT_PASS"

La salida tiene una sección por versión del protocolo. Su formato exacto depende de la versión de la CLI, pero se parece a esto (los valores varían según el broker y su configuración):

MQTT 3: OK
	- Maximum topic length: ... bytes
	- QoS 0: Received .../10 publishes in ...ms
	- QoS 1: ...
	- QoS 2: ...
	- Retain: OK
	- Wildcard subscriptions: OK
	- Shared subscriptions: OK
	- Payload size: >= ... bytes
	- Maximum client id length: ... bytes
MQTT 5: OK
	- Connect restrictions:
		> Retain: OK
		> Wildcard subscriptions: OK
		> Shared subscriptions: OK
		> Subscription identifiers: OK
		> Maximum QoS: 2
		> Receive maximum: ...
		> Maximum packet size: ... bytes
		> Topic alias maximum: ...
		> Session expiry interval: ...
		> Server keep alive: ...

Las «connect restrictions» de MQTT 5 salen directamente de las propiedades del CONNACK que envía el broker; las líneas de MQTT 3 se miden publicando y suscribiéndose de verdad. Añade -a (--all) para ejecutar también los tests de MQTT 3 cuando MQTT 5 funciona, y -V 3 o -V 5 para limitar el test a una versión. Si necesitas la misma información dentro de tus propias herramientas, prueba qué funciones de MQTT soporta un broker muestra cómo construir la sonda en Python.

Valores por defecto y scripts

Escribir -h broker.connectmq.com -p 8883 -s cada vez cansa. mqtt-cli lee valores por defecto como host, puerto, versión del protocolo y prefijo del client ID desde un archivo de propiedades en ~/.mqtt-cli/; consulta la documentación de tu versión para ver las claves exactas. Con los valores definidos, mqtt pub -t x -m y va a tu broker.

Un smoke test mínimo para un script de shell o un job de CI:

#!/usr/bin/env bash
set -euo pipefail
TOPIC="testmqtt/cli/smoke-$RANDOM"

mqtt pub -h broker.connectmq.com -p 1883 -t "$TOPIC" -m 'ping' -r -q 1
# un mensaje retenido se entrega en cuanto te suscribes; escuchar 5 s
OUT=$(timeout 5 mqtt sub -h broker.connectmq.com -p 1883 -t "$TOPIC" -q 1 || true)
echo "$OUT" | grep -q 'ping' && echo "OK" || { echo "FAIL: '$OUT'"; exit 1; }
# borrar el mensaje retenido
mqtt pub -h broker.connectmq.com -p 1883 -t "$TOPIC" -m '' -r

El mensaje retenido hace que el test no dependa del timing: el suscriptor lo recibe en cuanto la suscripción está activa. Para más patrones, consulta scripting MQTT en bash y los ejemplos de mosquitto_pub y mosquitto_sub; el cliente online es una forma rápida de observar el mismo topic desde el navegador mientras corre el script.

Mira el tráfico de mqtt-cli en el navegador

mqtt-cli es un cliente de terminal sólido por defecto: flags completas para MQTT 5, una shell para escenarios con varios clientes y un test de funciones del broker integrado. Guarda unos cuantos comandos en tu repositorio y cualquier compañero podrá reproducir un problema del broker de la misma forma.

Preguntas frecuentes