HiveMQ MQTT CLI: teste qualquer broker pelo terminal

A HiveMQ MQTT CLI (mqtt-cli) é um cliente de linha de comando open source, baseado em Java, que funciona com qualquer broker MQTT. O comando é simplesmente mqtt, e quatro subcomandos cobrem quase todo teste pelo terminal: mqtt pub, mqtt sub, o shell interativo mqtt shell e o mqtt test, que verifica o que um broker suporta.

Este guia mostra como instalá-la, conectar a um broker real com TLS e credenciais, usar propriedades do MQTT 5 e rodar o teste de recursos — com comandos prontos para colar.

Instalar o mqtt-cli

As versões recentes também trazem binários nativos, então nem sempre é preciso ter Java. Confira a instalação com mqtt --version. Com Docker, o entry point da imagem é a CLI, então docker run --rm -it hivemq/mqtt-cli pub -h ... substitui mqtt pub -h ....

Publicar e assinar

Abra dois terminais. Inicie o assinante primeiro, para que ele esteja escutando quando a mensagem chegar:

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 o topic antes de cada payload, o que é necessário ao assinar com wildcards. As opções mais usadas:

Duas flags do assinante são úteis em scripts: -J (--jsonOutput) imprime cada mensagem como um objeto JSON com topic, QoS e payload, e -of messages.log (--outputToFile) grava tudo em um arquivo. Passe o JSON pelo jq e você tem uma ferramenta rápida de asserções.

Credenciais e 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) ativa TLS com o trust store do sistema. Para um broker com CA privada, adicione --cafile ca.pem; para TLS mútuo, adicione --cert client.pem --key client.key. Um handshake com falha imprime uma exceção SSL do Java — veja testar a conexão TLS para isolar antes os problemas de certificado com openssl.

WebSocket

Apps de navegador chegam ao broker via WebSocket, e às vezes proxies quebram justamente esse caminho. Teste diretamente:

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

Se isso funciona mas o seu app web não, o problema está no navegador (conteúdo misto, CORS, URL errada), não no broker.

Propriedades do MQTT 5

O mqtt pub expõe as propriedades do PUBLISH do MQTT 5 como flags, o que é prático para verificar se um broker as repassa:

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'

Isso define duas user properties, um content type, um message expiry de 60 segundos, um response topic e correlation data. Rode o assinante com -J e as propriedades aparecem na saída. O guia de testes de recursos do MQTT 5 explica o que cada propriedade deve fazer e como verificar.

O shell interativo

mqtt shell abre um REPL em que você mantém vários clientes conectados ao mesmo tempo e alterna entre eles — perfeito para reproduzir interações como tomada de sessão ou assinaturas no-local sem abrir cinco terminais.

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 um novo cliente e o torna o contexto ativo; pub, sub e unsub agem sobre o cliente ativo; switch troca o contexto; ls lista os clientes conectados; dis desconecta. As mensagens recebidas por um cliente assinante são impressas no shell assim que chegam. Um experimento rápido: conecte um segundo cliente com o mesmo -i sensor-1 e veja o primeiro ser desconectado — o sintoma clássico de client ID duplicado.

mqtt test: descubra o que o broker suporta

O mqtt test se conecta a um broker e informa quais recursos do MQTT funcionam. É a forma mais rápida de responder "esse broker suporta MQTT 5, QoS 2, mensagens retidas e assinaturas compartilhadas?"

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

A saída tem uma seção por versão do protocolo. O layout exato depende da versão da CLI, mas é parecido com isto (os valores variam conforme o broker e a configuração):

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

As "connect restrictions" do MQTT 5 vêm direto das propriedades do CONNACK enviadas pelo broker; as linhas do MQTT 3 são medidas publicando e assinando de verdade. Adicione -a (--all) para também rodar os testes do MQTT 3 quando o MQTT 5 funcionar, e -V 3 ou -V 5 para limitar o teste a uma versão. Se você precisa da mesma informação nas suas próprias ferramentas, teste quais recursos do MQTT um broker suporta mostra como construir a sonda em Python.

Padrões e scripts

Digitar -h broker.connectmq.com -p 8883 -s toda hora cansa. O mqtt-cli lê valores padrão como host, porta, versão do protocolo e prefixo do client ID de um arquivo de propriedades em ~/.mqtt-cli/ — consulte a documentação da sua versão para as chaves exatas. Com os padrões definidos, mqtt pub -t x -m y vai para o seu broker.

Um smoke test mínimo para um script de shell ou 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
# uma mensagem retida é entregue logo ao assinar; escutar por 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; }
# limpar a mensagem retida
mqtt pub -h broker.connectmq.com -p 1883 -t "$TOPIC" -m '' -r

A mensagem retida torna o teste independente de timing: o assinante a recebe assim que a assinatura fica ativa. Para mais padrões, veja scripts MQTT em bash e os exemplos de mosquitto_pub e mosquitto_sub; o cliente online é um jeito rápido de acompanhar o mesmo topic pelo navegador enquanto o script roda.

Veja o tráfego do mqtt-cli no navegador

O mqtt-cli é um ótimo cliente de terminal padrão: flags completas para MQTT 5, um shell para cenários com vários clientes e um teste de recursos do broker embutido. Guarde alguns comandos no repositório e qualquer pessoa do time vai conseguir reproduzir um problema do broker do mesmo jeito.

Perguntas frequentes