mqtt-publish

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):

1. Topic — the exact topic to publish to. No wildcards allowed on publish.
2. Payload — string or JSON. If the user gives a JSON object, send it verbatim.
3. QoS — 0, 1, or 2. Default 0.
4. 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).