mqtt-exec(1)

📦 version 0.7.1, in alpine 3.24

💅 mqtt-exec — the manual page, but make it make sense

okay so bestie, welcome to mqtt-exec(1) from the General Commands Manual ✨ this is genuinely one of my fave little tools and i'm gonna walk you through it like we're texting at 2am 🫶

🌸 NAME 🌸

mqtt-exec — execute a command for MQTT messages. that's it. that's the whole vibe. a message comes in, a command goes out. iconic behavior fr 💅

✨ SYNOPSIS ✨

mqtt-exec [options...] -t topic... -- command [args...]

like, options first, at least one -t topic, then the sacred -- divider, then your command and its args. the -- is NOT optional bestie, respect the boundary 🎀

🦋 DESCRIPTION 🦋

so what does it actually do? mqtt-exec connects to an MQTT broker, subscribes to one or more topics, and executes a command when messages are received. that's the whole loop. no cap. 🔥

By default, the message payload is passed as the last argument to the configured command. When -v is used, the topic is passed as the second-to-last argument and the payload is passed as the last argument. so -v just slides the topic in right before the payload, cute 😌

Empty payloads are ignored unless -v is enabled. so if nothing's in the message, nothing happens — unless you're in verbose mode, in which case the empty payload still gets its little moment 🫶

After each successful connection, mqtt-exec can optionally publish an "up" status message before waiting for subscribed messages. lowkey a little "hey i'm here" text to the group chat 💖

When --status-down-payload is configured, mqtt-exec publishes that message on clean shutdown. Unexpected termination is still handled separately through the MQTT will configured with --will- options. so like, the polite goodbye is one thing, and the dramatic exit is a whole separate mechanism, and they do NOT overlap 🫠

okay this next bit matters: the clean-shutdown status publish is best effort. mqtt-exec attempts to flush it before disconnecting, but does not wait for a full QoS 1 or QoS 2 delivery handshake before exiting. so it tries its best and then leaves. main character energy but with a caveat 😭

🎀 OPTIONS 🎀

here's the whole menu, no skipping, i would never 🙈

  • -c, --disable-clean-session — Disable the MQTT clean session flag.
  • -d, --debug — Enable debug output from the MQTT client library. it gets chatty, you've been warned 💀
  • -h, --host host — Connect to host. The default is localhost.
  • -i, --id id — Set the client identifier.
  • -k, --keepalive seconds — Set the MQTT keepalive interval. The default is 60.
  • -p, --port port — Connect to TCP port. The default is 1883.
  • -P, --password password — Set the password used for authentication.
  • -q, --qos qos — Set the subscription QoS. Valid values are 0, 1, and 2.
  • -t, --topic topic — Subscribe to topic. This option may be given more than once. stack 'em bestie 🧚
  • -u, --username username — Set the username used for authentication.
  • -v, --verbose — Pass the MQTT topic as an additional command argument before the payload.
  • --version — Print the program version and exit.
  • --will-topic topic — Set the MQTT will topic.
  • --will-payload payload — Set the MQTT will payload.
  • --will-qos qos — Set the MQTT will QoS. Valid values are 0, 1, and 2.
  • --will-retain — Publish the MQTT will as a retained message.
  • --status-topic topic — Publish status transitions to topic.
  • --status-up-payload payload — Set the payload used after each successful connection. If omitted, an empty payload is sent.
  • --status-down-payload payload — Set the payload used on clean shutdown. This publish is best effort.
  • --status-qos qos — Set the QoS for status publishes. Valid values are 0, 1, and 2.
  • --status-retain — Publish status messages as retained messages.
  • --ready-fd fd — Write a newline to file descriptor fd after the initial connection and subscription setup succeeds, then close it. This can be used by test harnesses or service supervisors that need an explicit readiness signal. it's basically a little "i'm ready ✨" tap on the shoulder 🎀

🌈 TLS OPTIONS 🌈

When built with TLS support, the following options are available. note the when — if your build doesn't have TLS, these simply aren't there, no cap 🫶

  • --cafile file — Path to a CA certificate file.
  • --capath directory — Path to a directory containing CA certificates.
  • --cert file — Path to the client certificate.
  • --key file — Path to the client private key.
  • --ciphers list — OpenSSL-compatible cipher list.
  • --tls-version version — Set the TLS protocol version.
  • --psk key — Set the TLS pre-shared key in hexadecimal form.
  • --psk-identity identity — Set the TLS PSK identity string.

🍓 ENVIRONMENT 🍓

  • MQTT_EXEC_PASSWORD — Used as the password when --username is set and no password is provided on the command line. secret via env var, very spy, very demure 💜

👑 EXAMPLES 👑

Show MQTT messages as desktop notifications 💖

$ mqtt-exec -h "$mqtt_host" -t "$topic" -v --
     /usr/bin/notify-send -t 3000 -i network-server

the -v is doing the work there so notify-send gets the topic too. slay.

Run a script for retained messages on startup and for later live messages 🔥

$ mqtt-exec -h broker.example.com -t sensors/door -- /usr/local/bin/on-door-event

Publish presence status and process messages 🌸

$ mqtt-exec -h broker.example.com
     -t sensors/door
     --status-topic service/mqtt-exec/status
     --status-up-payload online
     --status-down-payload offline
     --will-topic service/mqtt-exec/status
     --will-payload failed
     --status-retain
     -- /usr/local/bin/on-door-event

look at all that presence info — online when it's up, offline on a clean shutdown, failed via the will if it dies unexpectedly. full personality, fully transparent, we love an accountable queen 👑

🧚 SEE ALSO 🧚

mosquitto_sub(1), mosquitto_pub(1) — go read those too, they're the siblings and they also ate 💅

quick vibe check reminder: everything above is exactly what the page says, i just made it fun. don't come for me if you skipped the bit about the clean-shutdown publish being best effort 😭

this has been mqtt-exec(1) from the General Commands Manual, dated 2026-05-18, and yes the footer also says mqtt-exec(1) because it's consistent like that 💜

later bestie, go exec some commands 🦋✨

📦 where this page comes from