| name | mqtt-publish |
| description | Publish (send) a payload to a specific MQTT topic on the configured broker. Use when the user wants to trigger an automation, send a test message, control a Zigbee/Home-Assistant device, or inject a payload for debugging. Requires `/mqtt-setup` to have been run previously. |
Publish an MQTT payload
Send a single message to a topic.
Gather inputs
From the user's invocation (or by asking if missing):
- Topic — the exact topic to publish to. No wildcards allowed on publish.
- Payload — string or JSON. If the user gives a JSON object, send it verbatim.
- QoS — 0, 1, or 2. Default
0.
- Retain —
true / false. Default false. Warn the user before publishing with retain, since it persists on the broker.
Load credentials
if [ ! -f ~/.claude/plugins-data/mqtt-observability/credentials.env ]; then
echo "No MQTT credentials found. Run /mqtt-setup first." >&2
exit 1
fi
set -a; . ~/.claude/plugins-data/mqtt-observability/credentials.env; set +a
Publish
mosquitto_pub -h "$MQTT_HOST" -p "$MQTT_PORT" \
${MQTT_USERNAME:+-u "$MQTT_USERNAME"} \
${MQTT_PASSWORD:+-P "$MQTT_PASSWORD"} \
-t "<topic>" \
-m "<payload>" \
-q <qos> \
${RETAIN:+-r}
For multi-line or complex JSON payloads, write the payload to a temp file and use -f:
mosquitto_pub ... -f /tmp/mqtt-payload.json
Confirm before sending
For any publish that could cause real-world side effects (device control, HA automation trigger, retained broadcast), echo the exact command back to the user and confirm before running. For pure observability test payloads on a test/* topic, proceed without confirmation.
Report
Tell the user:
- Topic published to
- Payload sent (truncated if very large)
- QoS / retain flags
- Exit code of
mosquitto_pub
Dependency
mosquitto-clients (sudo apt install mosquitto-clients).
