Las herramientas CLI de MQTT son la forma más rápida de responder a «¿mi dispositivo está publicando de verdad?» sin escribir una sola línea de código. Esta comparativa ejecuta las mismas tareas con seis clientes de línea de comandos, mosquitto_pub/sub, MQTTX CLI, HiveMQ MQTT CLI, la CLI de MQTT.js, curl y mqttui, para que veas su sintaxis lado a lado y elijas la adecuada. Todos los comandos apuntan al servidor MQTT público gratuito broker.connectmq.com, así que puedes probarlos mientras lees.
Qué hace bueno a un cliente MQTT de línea de comandos
Antes de comparar, conviene tener claro qué necesitas de una herramienta de terminal. Cada tarea favorece a herramientas distintas:
- Comprobaciones rápidas: publicar un mensaje, observar un topic. Importan la velocidad de arranque y una sintaxis corta.
- Scripts y CI: códigos de salida predecibles, «recibir N mensajes y salir», tiempos límite, salida legible por máquinas.
- Depuración del protocolo: mostrar el flujo de paquetes, los reason codes y las propiedades de MQTT 5.
- Exploración: navegar de forma interactiva por un árbol de topics desconocido.
- Carga y simulación: muchos clientes, payloads generados (se trata aparte en herramientas de pruebas de carga MQTT).
En el broker público, define siempre un client ID único, usa un prefijo de topic único como connectmq/demo/c1t9/ y recuerda que cualquiera puede leer todo lo que hay ahí.
Las seis herramientas CLI de MQTT de un vistazo
| Herramienta | Instalación | MQTT 5 | TLS | Punto fuerte | Punto débil |
|---|---|---|---|---|---|
| mosquitto_pub / mosquitto_sub | Paquete del sistema mosquitto-clients |
Sí | Sí | Omnipresente, diminuta, scriptable, excelente formato de salida | Binarios separados, errores escuetos |
| MQTTX CLI | npm, Homebrew o binario | Sí | Sí | Salida amigable, benchmarks y simuladores integrados | Instalación más pesada (basada en Node) |
| HiveMQ MQTT CLI | Homebrew, paquete o JAR | Sí (por defecto) | Sí | Modo shell interactivo, salida clara de MQTT 5 | Algunas instalaciones necesitan Java |
| CLI de MQTT.js | npm install -g mqtt |
Sí | Sí | Ya la tienes si usas Node | Menos opciones que las demás |
| curl | Normalmente preinstalado | No (3.1.1) | Sí (mqtts://) |
Cero instalación en la mayoría de sistemas | Solo QoS 0, funciones básicas |
| mqttui | Cargo o binario | Depende de la versión | Sí | Interfaz de terminal interactiva con árbol de topics | No está pensada para scripts |
mosquitto_pub y mosquitto_sub
Las herramientas de referencia. Si un servidor o una Raspberry Pi tiene algún cliente MQTT, probablemente sea este.
mosquitto_sub -h broker.connectmq.com -p 1883 -i cli-cmp-sub1 -t 'connectmq/demo/c1t9/#' -v
mosquitto_pub -h broker.connectmq.com -p 1883 -i cli-cmp-pub1 -t connectmq/demo/c1t9/test -m 'hello' -q 1
Para scripts destacan -C (salir tras N mensajes), -W (tiempo límite) y -F con %j para obtener salida JSON que puedes pasar a jq. -d imprime cada paquete, lo que zanja al instante cualquier discusión sobre el comportamiento del QoS. Hemos reunido 25 comandos listos para usar en los ejemplos de mosquitto_pub y mosquitto_sub.
# Comprobación de salud en un script: falla si no hay lectura en 10 segundos
if ! mosquitto_sub -h broker.connectmq.com -p 1883 -i health-c1t9 \
-t connectmq/demo/c1t9/sensor/temp -C 1 -W 10 > /dev/null; then
echo "sensor silent" >&2; exit 1
fi
MQTTX CLI
MQTTX CLI es la hermana de línea de comandos de la aplicación de escritorio MQTTX. Su salida tiene colores y es legible, e incluye los subcomandos bench y simulate, que las demás herramientas no tienen.
mqttx sub -h broker.connectmq.com -p 1883 -i cli-cmp-sub2 -t 'connectmq/demo/c1t9/#' -v
mqttx pub -h broker.connectmq.com -p 1883 -i cli-cmp-pub2 -t connectmq/demo/c1t9/test -m 'hello' -q 1
mqttx conn -h broker.connectmq.com -p 8883 -l mqtts -i cli-cmp-conn2
El flag -l mqtts selecciona TLS; -V 5 o -V 3.1.1 elige la versión del protocolo (MQTT 5 es el valor por defecto en las versiones recientes). Para obtener rápidamente datos realistas, el comando simulate publica payloads generados a partir de escenarios integrados o personalizados, algo muy práctico cuando el firmware aún no está listo. Mantén las tasas generadas dentro de los límites del broker; en el broker público eso significa como máximo 10 mensajes por segundo por cliente.
HiveMQ MQTT CLI
La CLI de HiveMQ es un único comando mqtt con subcomandos y usa MQTT 5 por defecto. Su función estrella es el modo shell: te conectas una vez y luego escribes comandos de forma interactiva, como si fuera un REPL para MQTT.
mqtt sub -h broker.connectmq.com -p 1883 -i cli-cmp-sub3 -t 'connectmq/demo/c1t9/#'
mqtt pub -h broker.connectmq.com -p 1883 -i cli-cmp-pub3 -t connectmq/demo/c1t9/test -m 'hello' -q 1
# Shell interactiva
mqtt shell
Dentro de la shell, con -h broker.connectmq.com -i cli-cmp-shell3 abre una conexión, y los comandos pub y sub posteriores la reutilizan. Añade -V 3 cuando necesites probar el comportamiento de MQTT 3.1.1, y -s para TLS con el trust store por defecto.
Cuidado con un conflicto de nombres: tanto la CLI de HiveMQ como la de MQTT.js instalan un comando llamado mqtt. Si tienes las dos, gana la que aparezca primero en tu PATH.
CLI de MQTT.js
Si ya trabajas con Node.js, el paquete MQTT.js incluye su propia CLI. Cubre lo básico y usa las mismas letras de opción que mosquitto para los flags habituales.
npm install -g mqtt
mqtt sub -h broker.connectmq.com -p 1883 -i cli-cmp-sub4 -t 'connectmq/demo/c1t9/#' -v
mqtt pub -h broker.connectmq.com -p 1883 -i cli-cmp-pub4 -t connectmq/demo/c1t9/test -m 'hello'
No es la opción con más funciones, pero es la misma biblioteca que usa tu aplicación Node, así que el comportamiento coincide exactamente. Para el código de la aplicación, continúa con MQTT.js en Node.js.
curl
Poca gente sabe que curl habla MQTT. Solo admite MQTT 3.1.1 con QoS 0 y no tiene opciones de retención ni de Will, pero está instalado en la mayoría de los sistemas Linux y macOS y en muchas imágenes base de contenedores (comprueba que mqtt aparece en la lista de protocolos de curl -V).
# Suscribirse (imprime los payloads en bruto; Ctrl+C para parar)
curl -s mqtt://broker.connectmq.com:1883/connectmq%2Fdemo%2Fc1t9%2Ftest
# Publicar
curl -d 'hello from curl' mqtt://broker.connectmq.com:1883/connectmq%2Fdemo%2Fc1t9%2Ftest
Codifica las barras del topic como %2F. curl genera su propio client ID, así que no puedes usarlo con brokers que exigen un client ID concreto por credencial. Para algo más que una prueba de humo, usa una de las herramientas dedicadas.
mqttui
mqttui es una interfaz de usuario de terminal escrita en Rust. Muestra un árbol de topics en vivo, el último payload y gráficos de historial sencillos para valores numéricos, todo en la terminal, lo que la hace perfecta por SSH, donde no puedes ejecutar una aplicación de escritorio.
mqttui --broker mqtt://broker.connectmq.com:1883 'connectmq/demo/c1t9/#'
Es una herramienta de exploración, no de scripting. Para una vista gráfica más rica, consulta las aplicaciones de escritorio tipo MQTT Explorer.
La misma prueba en todas las herramientas
Una comparación justa es una misma tarea hecha en todas partes: suscribirse a connectmq/demo/c1t9/#, publicar un mensaje QoS 1 en connectmq/demo/c1t9/test y salir tras recibirlo.
| Herramienta | Recibir y salir (un mensaje o tiempo límite) |
|---|---|
| mosquitto_sub | mosquitto_sub -h broker.connectmq.com -i s1-c1t9 -t 'connectmq/demo/c1t9/#' -C 1 |
| MQTTX CLI | timeout 10 mqttx sub -h broker.connectmq.com -i s2-c1t9 -t 'connectmq/demo/c1t9/#' (o una opción de recuento si tu versión la tiene) |
| HiveMQ CLI | timeout 10 mqtt sub -h broker.connectmq.com -i s3-c1t9 -t 'connectmq/demo/c1t9/#' |
| CLI de MQTT.js | timeout 10 mqtt sub -h broker.connectmq.com -i s4-c1t9 -t 'connectmq/demo/c1t9/#' |
| curl | timeout 5 curl -s mqtt://broker.connectmq.com/connectmq%2Fdemo%2Fc1t9%2Ftest |
Por eso mosquitto_sub sigue siendo la opción por defecto en los pipelines de CI: -C y -W convierten «espera exactamente un mensaje o falla» en una sola línea. Consulta --help en las versiones instaladas de las demás herramientas, porque las opciones cambian entre versiones.
¿Qué herramienta CLI de MQTT deberías usar?
- En servidores, Raspberry Pi y CI: los clientes mosquitto. Pequeños, empaquetados en todas partes, los mejores para scripts.
- Para el desarrollo diario en un portátil: MQTTX CLI o HiveMQ CLI. Salida legible y detalles de MQTT 5 por defecto.
- Para depurar el comportamiento de MQTT 5 de forma interactiva: el modo shell de HiveMQ CLI.
- En un proyecto Node: la CLI de MQTT.js, para que las pruebas coincidan con el comportamiento de producción.
- En un contenedor vacío sin nada instalado: curl para una prueba de humo con QoS 0.
- Por SSH, explorando topics desconocidos: mqttui.
Muchos equipos se quedan con dos: los clientes mosquitto para automatización y una herramienta más amigable para las personas. Si prefieres no salir nunca de tu editor, la guía de la extensión MQTT para VS Code muestra ese flujo de trabajo.
Uso de herramientas CLI con un broker privado
Todas las herramientas anteriores aceptan las mismas tres cosas para un broker de producción: host y puerto TLS, credenciales y client ID. Con ConnectMQ, el portal genera las tres al crear un broker:
mosquitto_sub -h YOUR_BROKER_HOST -p 8883 --capath /etc/ssl/certs \
-i YOUR_CLIENT_ID -u YOUR_USERNAME -P YOUR_PASSWORD -t '#' -v
Como los client ID están vinculados a las credenciales emitidas, usa exactamente el client ID del portal; un ID aleatorio será rechazado. El certificado lo emite Let's Encrypt, así que los trust stores del sistema funcionan sin archivos adicionales en la mayoría de las distribuciones Linux. El broker también acepta WebSocket en el 8083 y WebSocket seguro en el 8084 con la ruta /mqtt para las herramientas que lo admiten.
Usa el servidor MQTT público gratuito para aprender y hacer experimentos rápidos, y un broker MQTT gestionado para cualquier cosa que implique dispositivos o datos reales. Para ver cómo encajan las pruebas por CLI en un flujo de desarrollo más amplio, la visión general de bibliotecas cliente MQTT relaciona las comprobaciones por CLI con el código en cada lenguaje.
Empieza con ConnectMQ
Crea un broker privado en app.connectmq.com con el plan Serverless gratuito, sin tarjeta de crédito, y apunta a él tu herramienta CLI favorita. El cliente MQTT integrado en el navegador y el explorador de topics en vivo del portal son una cómoda segunda vista mientras depuras desde la terminal.
Preguntas frecuentes
¿Cuál es la mejor herramienta CLI de MQTT para principiantes?
MQTTX CLI o HiveMQ CLI, porque su salida es más fácil de leer y usan MQTT 5 por defecto. Aprende después mosquitto_pub y mosquitto_sub, porque las encontrarás en casi todos los servidores.
¿Puedo probar MQTT sin instalar nada?
A menudo sí: curl admite publicación y suscripción MQTT básicas en la mayoría de los sistemas. El portal de ConnectMQ también incluye un cliente MQTT en el navegador para tu propio broker.
¿Qué herramienta CLI muestra los reason codes de MQTT 5?
Todas las herramientas compatibles con MQTT 5 los muestran, pero los clientes mosquitto con -d y la CLI de HiveMQ son los que muestran con más claridad el intercambio de paquetes.
¿Por qué mi cliente CLI se desconecta una y otra vez?
Normalmente porque otro cliente está usando el mismo client ID, así que el broker desconecta la conexión más antigua. Da a cada terminal su propio ID.
