As ferramentas CLI MQTT são a forma mais rápida de responder "meu dispositivo está mesmo publicando?" sem escrever uma linha de código. Esta comparação executa as mesmas tarefas em seis clientes de linha de comando, mosquitto_pub/sub, MQTTX CLI, HiveMQ MQTT CLI, a CLI do MQTT.js, curl e mqttui, para que você veja a sintaxe lado a lado e escolha a certa. Todos os comandos usam o servidor MQTT público (gratuito) broker.connectmq.com, então você pode testá-los enquanto lê.
O que faz um bom cliente MQTT de linha de comando
Antes de comparar, vale deixar claro o que você precisa de uma ferramenta de terminal. Tarefas diferentes favorecem ferramentas diferentes:
- Verificações rápidas: publicar uma mensagem, observar um topic. Velocidade de inicialização e sintaxe curta importam.
- Scripts e CI: códigos de saída previsíveis, "receber N mensagens e sair", timeouts, saída legível por máquina.
- Depuração de protocolo: mostrar o fluxo de pacotes, reason codes e propriedades do MQTT 5.
- Exploração: navegar de forma interativa por uma árvore de topics desconhecida.
- Carga e simulação: muitos clientes, payloads gerados (abordado separadamente em ferramentas de teste de carga MQTT).
No servidor MQTT público, sempre defina um client ID único, use um prefixo de topic exclusivo como connectmq/demo/c1t9/ e lembre-se de que tudo ali pode ser lido por qualquer pessoa: ele serve para testes e protótipos, não para dados de produção.
As seis ferramentas CLI MQTT em resumo
| Ferramenta | Instalação | MQTT 5 | TLS | Ponto forte | Ponto fraco |
|---|---|---|---|---|---|
| mosquitto_pub / mosquitto_sub | Pacote do SO mosquitto-clients |
Sim | Sim | Onipresente, minúscula, scriptável, excelente formatação da saída | Binários separados, erros lacônicos |
| MQTTX CLI | npm, Homebrew ou binário | Sim | Sim | Saída amigável, benchmarks e simuladores embutidos | Instalação maior (baseada em Node) |
| HiveMQ MQTT CLI | Homebrew, pacote ou JAR | Sim (padrão) | Sim | Modo shell interativo, saída clara do MQTT 5 | Algumas instalações exigem runtime Java |
| CLI do MQTT.js | npm install -g mqtt |
Sim | Sim | Já está lá se você usa Node | Menos opções que as outras |
| curl | Normalmente pré-instalado | Não (3.1.1) | Sim (mqtts://) |
Nenhuma instalação na maioria dos sistemas | Apenas QoS 0, recursos básicos |
| mqttui | Cargo ou binário | Depende da versão | Sim | Interface de terminal interativa com árvore de topics | Não serve para scripts |
mosquitto_pub e mosquitto_sub
As ferramentas de referência. Se um servidor ou Raspberry Pi tem algum cliente MQTT, provavelmente é 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
O que se destaca para scripts é o -C (sai após N mensagens), o -W (timeout) e o -F com %j para saída JSON que pode ser encaminhada ao jq. O -d imprime cada pacote, o que encerra na hora qualquer discussão sobre o comportamento do QoS. Reunimos 25 comandos prontos em exemplos de mosquitto_pub e mosquitto_sub.
# Health check em um script: falha se nenhuma leitura chegar em 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
A MQTTX CLI é a irmã de linha de comando do app desktop MQTTX. Sua saída é colorida e legível, e ela inclui os subcomandos bench e simulate, que as outras ferramentas não têm.
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
A flag -l mqtts seleciona TLS; -V 5 ou -V 3.1.1 escolhe a versão do protocolo (o MQTT 5 é o padrão nas versões recentes). Para obter dados realistas rapidamente, o comando simulate publica payloads gerados a partir de cenários embutidos ou personalizados, o que é útil quando o firmware ainda não está pronto. Mantenha as taxas geradas dentro dos limites do broker; no broker público, isso significa no máximo 10 mensagens por segundo por cliente.
HiveMQ MQTT CLI
A CLI da HiveMQ é um único comando mqtt com subcomandos e usa MQTT 5 por padrão. Seu recurso de destaque é o modo shell: você se conecta uma vez e depois digita comandos de forma interativa, como em um 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 interativo
mqtt shell
Dentro do shell, con -h broker.connectmq.com -i cli-cmp-shell3 abre uma conexão, e os comandos pub e sub seguintes a reutilizam. Adicione -V 3 quando precisar testar o comportamento do MQTT 3.1.1 e -s para TLS com o trust store padrão.
Atenção a um conflito de nomes: tanto a HiveMQ CLI quanto a CLI do MQTT.js instalam um comando chamado mqtt. Se você tiver as duas, vence a que aparecer primeiro no seu PATH.
CLI do MQTT.js
Se você já trabalha com Node.js, o pacote MQTT.js traz a própria CLI. Ela cobre o básico e usa as mesmas letras de opção do mosquitto para as flags mais comuns.
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'
Não é a opção mais completa, mas é a mesma biblioteca que a sua aplicação Node usa, então o comportamento corresponde exatamente. Para código de aplicação, continue com MQTT.js no Node.js.
curl
Pouca gente sabe que o curl fala MQTT. Ele suporta apenas MQTT 3.1.1 com QoS 0 e não tem opções de retain ou Will, mas está instalado na maioria dos sistemas Linux e macOS e em muitas imagens base de contêiner (confira curl -V e procure mqtt na lista de protocolos).
# Assinar (imprime os payloads brutos; 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
Codifique as barras do topic como %2F. O curl gera o próprio client ID, então você não pode usá-lo em brokers que exigem um client ID específico por credencial. Para qualquer coisa além de um smoke test, use uma das ferramentas dedicadas.
mqttui
O mqttui é uma interface de usuário de terminal escrita em Rust. Ele mostra uma árvore de topics ao vivo, o payload mais recente e gráficos simples de histórico para valores numéricos, tudo no terminal, o que é perfeito via SSH, onde não dá para rodar um app desktop.
mqttui --broker mqtt://broker.connectmq.com:1883 'connectmq/demo/c1t9/#'
É uma ferramenta de exploração, não de scripts. Para uma visão gráfica mais rica, veja os apps desktop de exploração MQTT.
O mesmo teste em todas as ferramentas
Uma comparação justa é uma única tarefa feita em todas elas: assinar connectmq/demo/c1t9/#, publicar uma mensagem QoS 1 em connectmq/demo/c1t9/test e sair após recebê-la.
| Ferramenta | Receber e sair (uma mensagem ou timeout) |
|---|---|
| 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/#' (ou uma opção de contagem, se a sua versão tiver) |
| HiveMQ CLI | timeout 10 mqtt sub -h broker.connectmq.com -i s3-c1t9 -t 'connectmq/demo/c1t9/#' |
| CLI do 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 isso que o mosquitto_sub continua sendo a escolha padrão em pipelines de CI: -C e -W transformam "esperar exatamente uma mensagem ou falhar" em uma única linha. Confira o --help das versões instaladas das outras ferramentas, já que as opções mudam entre releases.
Qual ferramenta CLI MQTT você deve usar?
- Em servidores, Raspberry Pis e CI: os mosquitto clients. Pequenos, empacotados em todo lugar, os melhores para scripts.
- No desenvolvimento diário no notebook: MQTTX CLI ou HiveMQ CLI. Saída legível e detalhes do MQTT 5 por padrão.
- Ao depurar o comportamento do MQTT 5 de forma interativa: o modo shell da HiveMQ CLI.
- Em um projeto Node: a CLI do MQTT.js, para que os testes reproduzam o comportamento de produção.
- Em um contêiner vazio, sem nada instalado: o curl para um smoke test com QoS 0.
- Via SSH, explorando topics desconhecidos: o mqttui.
Muitas equipes mantêm duas: os mosquitto clients para automação e uma ferramenta mais amigável para as pessoas. Se você prefere nunca sair do editor, o guia da extensão MQTT para VS Code mostra esse fluxo de trabalho.
Usando ferramentas CLI com um broker privado
Todas as ferramentas acima aceitam as mesmas três coisas para um broker de produção: host e porta TLS, credenciais e client ID. Com a ConnectMQ, o portal gera os três quando você cria um 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 os client IDs são vinculados às credenciais emitidas, use exatamente o client ID do portal; um ID aleatório será rejeitado. O certificado é emitido pela Let's Encrypt, então os trust stores do sistema funcionam sem arquivos extras na maioria das distribuições Linux. O broker também aceita WebSocket na 8083 e WebSocket seguro na 8084, no caminho /mqtt, para as ferramentas que oferecem suporte.
Use o servidor MQTT público para aprender e fazer experimentos rápidos, e um broker MQTT gerenciado para qualquer coisa que envolva dispositivos ou dados reais, como a telemetria de uma usina ou de uma linha de produção. Para ver como os testes via CLI se encaixam em um fluxo de desenvolvimento mais amplo, a visão geral de bibliotecas de cliente MQTT relaciona as verificações na CLI ao código em cada linguagem.
Comece a usar a ConnectMQ
Crie um broker privado em app.connectmq.com no plano Serverless gratuito, sem cartão de crédito, e aponte sua ferramenta CLI favorita para ele. O cliente MQTT no navegador e o explorador de topics em tempo real do portal são uma segunda visão prática enquanto você depura pelo terminal.
Perguntas frequentes
Qual é a melhor ferramenta CLI MQTT para iniciantes?
A MQTTX CLI ou a HiveMQ CLI, porque a saída delas é mais fácil de ler e ambas usam MQTT 5 por padrão. Aprenda o mosquitto_pub e o mosquitto_sub em seguida, porque você vai encontrá-los em quase todo servidor.
Posso testar MQTT sem instalar nada?
Muitas vezes, sim: o curl suporta publicação e assinatura MQTT básicas na maioria dos sistemas. O portal da ConnectMQ também inclui um cliente MQTT no navegador para o seu próprio broker.
Qual ferramenta CLI mostra os reason codes do MQTT 5?
Todas as ferramentas compatíveis com MQTT 5 os informam, mas os mosquitto clients com -d e a HiveMQ CLI mostram a troca de pacotes com mais clareza.
Por que meu cliente CLI é desconectado repetidamente?
Geralmente outro cliente está usando o mesmo client ID, então o broker desconecta a conexão mais antiga. Dê a cada terminal seu próprio ID.
