MQTT CLI tools are the quickest way to answer "is my device actually publishing?" without writing a line of code. This comparison runs the same tasks through six command-line clients, mosquitto_pub/sub, MQTTX CLI, HiveMQ MQTT CLI, the MQTT.js CLI, curl and mqttui, so you can see their syntax side by side and pick the right one. Every command targets the free public broker broker.connectmq.com, so you can try them as you read.
What Makes a Good MQTT Command-Line Client
Before comparing, it helps to be clear about what you need from a terminal tool. Different jobs favor different tools:
- Quick checks: publish one message, watch one topic. Startup speed and short syntax matter.
- Scripting and CI: predictable exit codes, "receive N messages then exit", timeouts, machine-readable output.
- Protocol debugging: show packet flow, reason codes and MQTT 5 properties.
- Exploration: browse an unfamiliar topic tree interactively.
- Load and simulation: many clients, generated payloads (covered separately in MQTT load testing tools).
On the public broker, always set a unique client ID, use a unique topic prefix such as connectmq/demo/c1t9/, and remember everything there is readable by anyone.
The Six MQTT CLI Tools at a Glance
| Tool | Install | MQTT 5 | TLS | Strength | Weak spot |
|---|---|---|---|---|---|
| mosquitto_pub / mosquitto_sub | OS package mosquitto-clients |
Yes | Yes | Ubiquitous, tiny, scriptable, excellent output formatting | Separate binaries, terse errors |
| MQTTX CLI | npm, Homebrew, or binary | Yes | Yes | Friendly output, built-in benchmarks and simulators | Larger install (Node based) |
| HiveMQ MQTT CLI | Homebrew, package, or JAR | Yes (default) | Yes | Interactive shell mode, clear MQTT 5 output | Needs Java runtime for some installs |
| MQTT.js CLI | npm install -g mqtt |
Yes | Yes | Already there if you use Node | Fewer options than the others |
| curl | Usually preinstalled | No (3.1.1) | Yes (mqtts://) |
Zero install on most systems | QoS 0 only, basic features |
| mqttui | Cargo or binary | Depends on version | Yes | Interactive terminal UI with topic tree | Not meant for scripting |
mosquitto_pub and mosquitto_sub
The reference tools. If a server or Raspberry Pi has any MQTT client, it is probably this one.
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
What stands out for scripting is -C (exit after N messages), -W (timeout), and -F with %j for JSON output you can pipe into jq. -d prints every packet, which settles arguments about QoS behavior instantly. We collected 25 ready-made commands in mosquitto_pub and mosquitto_sub examples.
# Health check in a script: fail if no reading within 10 seconds
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 is the command-line sibling of the MQTTX desktop app. Its output is colorized and readable, and it includes bench and simulate subcommands that the other tools lack.
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
The -l mqtts flag selects TLS; -V 5 or -V 3.1.1 picks the protocol version (MQTT 5 is the default in recent versions). For quick realistic data, the simulate command publishes generated payloads from built-in or custom scenarios, which is handy when firmware is not ready yet. Keep generated rates within broker limits; on the public broker that means at most 10 messages per second per client.
HiveMQ MQTT CLI
HiveMQ's CLI is a single mqtt command with subcommands, and it defaults to MQTT 5. Its standout feature is shell mode: you connect once and then type commands interactively, which feels like a REPL for 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
# Interactive shell
mqtt shell
Inside the shell, con -h broker.connectmq.com -i cli-cmp-shell3 opens a connection, and subsequent pub and sub commands reuse it. Add -V 3 when you need to test MQTT 3.1.1 behavior, and -s for TLS with the default trust store.
Watch out for a name clash: both HiveMQ CLI and the MQTT.js CLI install a command called mqtt. If you have both, whichever comes first on your PATH wins.
MQTT.js CLI
If you already work in Node.js, the MQTT.js package ships its own CLI. It covers the basics and uses the same option letters as mosquitto for common flags.
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'
It is not the most feature-rich option, but it is the same library your Node application uses, so behavior matches exactly. For application code, continue with MQTT.js in Node.js.
curl
Few people know that curl speaks MQTT. It supports only MQTT 3.1.1 at QoS 0 and has no retained or Will options, but it is installed on most Linux and macOS systems and in many container base images (check curl -V for mqtt in the protocol list).
# Subscribe (prints raw payloads; Ctrl+C to stop)
curl -s mqtt://broker.connectmq.com:1883/connectmq%2Fdemo%2Fc1t9%2Ftest
# Publish
curl -d 'hello from curl' mqtt://broker.connectmq.com:1883/connectmq%2Fdemo%2Fc1t9%2Ftest
Encode the slashes in the topic as %2F. curl generates its own client ID, so you cannot use it against brokers that require a specific client ID per credential. For anything more than a smoke test, use one of the dedicated tools.
mqttui
mqttui is a terminal user interface written in Rust. It shows a live topic tree, the latest payload and simple history graphs for numeric values, all in the terminal, which is perfect over SSH where you cannot run a desktop app.
mqttui --broker mqtt://broker.connectmq.com:1883 'connectmq/demo/c1t9/#'
It is an exploration tool, not a scripting tool. For a richer graphical view, see desktop MQTT explorer apps.
The Same Test in Every Tool
A fair comparison is one task done everywhere: subscribe to connectmq/demo/c1t9/#, publish one QoS 1 message to connectmq/demo/c1t9/test, and exit after receiving it.
| Tool | Receive and exit (one message or 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/#' (or a count option if your version has one) |
| HiveMQ CLI | timeout 10 mqtt sub -h broker.connectmq.com -i s3-c1t9 -t 'connectmq/demo/c1t9/#' |
| MQTT.js CLI | 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 |
This is why mosquitto_sub remains the default choice in CI pipelines: -C and -W make "wait for exactly one message or fail" a one-liner. Check --help in your installed versions of the other tools, since options evolve between releases.
Which MQTT CLI Tool Should You Use?
- On servers, Raspberry Pis and CI: mosquitto clients. Small, packaged everywhere, best for scripts.
- For daily development on a laptop: MQTTX CLI or HiveMQ CLI. Readable output and MQTT 5 details by default.
- When debugging MQTT 5 behavior interactively: HiveMQ CLI shell mode.
- In a Node project: MQTT.js CLI, so tests match production behavior.
- In a bare container with nothing installed: curl for a QoS 0 smoke test.
- Over SSH when exploring unknown topics: mqttui.
Many teams keep two: mosquitto clients for automation and one friendlier tool for humans. If you would rather never leave your editor, the VS Code MQTT extension guide shows that workflow.
Using CLI Tools with a Private Broker
Every tool above accepts the same three things for a production broker: host and TLS port, credentials and client ID. With ConnectMQ, the portal generates all three when you create a 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
Because client IDs are bound to issued credentials, use the exact client ID from the portal; a random ID will be rejected. The certificate is issued by Let's Encrypt, so system trust stores work without extra files on most Linux distributions. The broker also accepts WebSocket on 8083 and secure WebSocket on 8084 at path /mqtt for tools that support it.
Use the free public MQTT broker for learning and quick experiments, and a managed MQTT broker for anything involving real devices or data. To see how CLI testing fits into a broader development workflow, the MQTT client libraries overview maps CLI checks to code in each language.
Get Started with ConnectMQ
Create a private broker at app.connectmq.com on the free Serverless plan, no credit card needed, and point your favorite CLI tool at it. The portal's in-browser MQTT client and live topic explorer are a convenient second view while you debug from the terminal.
Frequently Asked Questions
What is the best MQTT CLI tool for beginners?
MQTTX CLI or the HiveMQ CLI, because their output is easier to read and they default to MQTT 5. Learn mosquitto_pub and mosquitto_sub next, because you will find them on almost every server.
Can I test MQTT without installing anything?
Often yes: curl supports basic MQTT publish and subscribe on most systems. The ConnectMQ portal also includes an in-browser MQTT client for your own broker.
Which CLI tool shows MQTT 5 reason codes?
All the MQTT 5-capable tools report them, but mosquitto clients with -d and the HiveMQ CLI show the packet exchange most clearly.
Why does my CLI client get disconnected repeatedly?
Usually another client is using the same client ID, so the broker disconnects the older connection. Give every terminal its own ID.
