How to Receive Retained Messages Using mosquitto_sub vs mqtt-cli

Here’s a comparison-style How-To guide that explains how to receive retained messages using both mosquitto_sub and mqtt-cli, with clear instructions and use cases for each.

This guide outlines how to retrieve retained MQTT messages using two popular tools:

mosquitto_sub
mqtt-cli

Both tools allow subscribing to topics and filtering for retained messages, but they differ in flexibility and output formatting.

Instructions

🛠 Prerequisites (Common to Both)

A running MQTT broker (e.g., HiveMQ)
Network access to the broker (IP or hostname and port)
Valid username/password if authentication is enabled
Known topic structure or use of wildcard (#)

🔹 Option 1: Using `mosquitto_sub`

✅ Best for:

Quick testing
Simple environments
Minimal dependencies

🔧 Command

mosquitto_sub -h <broker-host> -p <port> -u <username> -P <password> -t '#' -v --retained-only

📄 Output

Plain text in the format:

<topic> <message>

📌 Notes

--retained-only filters out non-retained messages.
Doesn't format JSON or allow structured filtering.
Not interactive or script-friendly for complex use cases.

🔹 Option 2: Using `mqtt-cli` + `jq`

✅ Best for:

Advanced filtering (e.g., JSON retained flag)
Automation or logging
Production diagnostics

🔧 Command

mqtt subscribe \
  --host <broker-host> \
  --port <port> \
  --identifier retained-subscriber \
  --topic '#' \
  --qos 0 \
  --user <username> \
  --password <password> \
  --json-output \
  | jq -c 'select(.retain == true)'

📄 Output

JSON formatted messages, e.g.:

{"topic":"sensor/temp","payload":"22.5","retain":true}

📌 Notes

Requires jq for JSON processing.
More scriptable and filterable than mosquitto_sub.
Supports TLS, structured output, and richer MQTT options.

🆚 Feature Comparison Table

Feature	`mosquitto_sub`	`mqtt-cli` + `jq`

Feature	`mosquitto_sub`	`mqtt-cli` + `jq`
Retained message filter	✅ `--retained-only`	✅ via `jq`
JSON Output	❌ Plain text only	✅ `--json-output`
Topic Wildcards	✅	✅
TLS/Authentication Support	✅	✅
Filtering (retain=true only)	🚫	✅ via `jq`
Script/Automation Friendly	⚠️ Basic only	✅ Excellent
Dependency	Low (1 CLI tool)	Medium (CLI + jq)

🧠 Summary

Use Case	Recommended Tool

Use Case	Recommended Tool
Quick testing, simple CLI use	`mosquitto_sub`
Structured filtering, automation	`mqtt-cli` + `jq`

How to Receive Retained Messages Using mosquitto_sub vs mqtt-cli

Instructions

🛠 Prerequisites (Common to Both)

🔹 Option 1: Using mosquitto_sub

✅ Best for:

🔧 Command

📄 Output

📌 Notes

🔹 Option 2: Using mqtt-cli + jq

✅ Best for:

🔧 Command

📄 Output

📌 Notes

🆚 Feature Comparison Table

🧠 Summary

Related articles

🔹 Option 1: Using `mosquitto_sub`

🔹 Option 2: Using `mqtt-cli` + `jq`