mqttui-clean-retained(1)

okay bestie, welcome to the mqttui-clean-retained(1) page from the General Commands Manual — this is the mqttui-clean-retained command, and it's here to clean retained messages from the broker. no cap, let's get into it 💅

✨ NAME ✨

mqttui-clean-retained — clean retained messages from the broker 🧹

🌸 SYNOPSIS 🌸

mqttui clean-retained [--timeout] [--dry-run] [--qos] [-b|--broker]
[-u|--username] [--password] [-i|--client-id] [--ca-cert]
[--client-cert] [--client-private-key] [--insecure] [-h|--help] <TOPIC>

🦋 DESCRIPTION 🦋

Okay so the whole vibe: it cleans retained messages from the broker.

It works by subscribing to the topic and waiting for messages with the retained flag. Then a message with an empty payload is published retained, which clears the topic on the broker. It ends on the first non retained message or when the timeout is reached. Periodt. ✨

💅 OPTIONS 💅

• --timeout <SECONDS> — default: 5. When there is no message received for the given time, the operation is considered done. ⏳
• --dry-run — Dont clean topics, only log them. So it's just logging, not cleaning, bestie 👀
• --qos <LEVEL> — default: 2. Maximum Quality of Service (QoS) for subscriptions and publishing.

The lower Quality of Service level for publisher and subscriber is delivered from broker to subscriber. So subscribing with 0 will never receive a 1 or 2. Publishing with 2 will be received as 1 when subscribed with 1.

• 0: at most once (fire and forget)
• 1: at least once (acknowledged delivery with potential duplicates)
• 2: exactly once (assured delivery without duplicates)

May also be specified with the MQTTUI_QOS environment variable. 🌸

• -h, --help — print help (see a summary with -h) 👑
• <TOPIC> — topic which gets cleaned. Supports filters like foo/bar/#. 🎯

🔌 MQTT CONNECTION 🔌

• -b, --broker <URL> — default: mqtt://localhost. URL which represents how to connect to the MQTT broker. May also be specified with the MQTTUI_BROKER environment variable. 🌈

Examples:

mqtt://localhost
mqtt://localhost:1883
mqtts://localhost
mqtts://localhost:8883
ws://localhost/path
ws://localhost:9001/path
wss://localhost/path
wss://localhost:9001/path

• -u, --username <STRING> — username to access the mqtt broker. Anonymous access when not supplied. May also be specified with the MQTTUI_USERNAME environment variable. 🫶
• --password <STRING> — password to access the mqtt broker. May also be specified with the MQTTUI_PASSWORD environment variable.

bestie, warning: consider using a connection with TLS to the broker. Otherwise the password will be transported in plaintext. Passing the password via command line is insecure as the password can be read from the history! You should pass it via environment variable. 🚨

• -i, --client-id <STRING> — specify the client id to connect with. May also be specified with the MQTTUI_CLIENTID environment variable. 👑
• --ca-cert <FILEPATH> — path to a trusted CA certificate PEM file for verifying the broker.

The CA certificate has to be a X.509 v3 certificate since rustls does not support the less secure v1 certificates. See: https://github.com/rustls/rustls/issues/2364

May also be specified with the MQTTUI_CA_CERTIFICATE environment variable. 🦋

• --client-cert <FILEPATH> — path to the TLS client certificate file.

Used together with --client-private-key to enable TLS client authentication. The file has to be a DER-encoded X.509 certificate serialized to PEM.

May also be specified with the MQTTUI_CLIENT_CERTIFICATE environment variable. 💖

• --client-private-key <FILEPATH> — path to the TLS client private key file.

Used together with --client-cert to enable TLS client authentication. The file has to be a DER-encoded ASN.1 file in PKCS#8 form serialized to PEM.

May also be specified with the MQTTUI_CLIENT_PRIVATE_KEY environment variable. 🔐

• --insecure — allow insecure TLS connections. 🙈

---

footer sign-off tea ☕: source label clean-retained, page mqttui-clean-retained(1), and the original footer didn't give a date or version line, so I'm not making one up — periodt 🫶