mqtt-tail

tail -f for MQTT. Watch topics stream live in your terminal.

16:42:03.112 │ sensors/temperature
{
  "value": 23.5,
  "unit": "C",
  "sensor": "living-room"
}

16:42:04.891 │ sensors/humidity
{
  "value": 61,
  "unit": "%"
}

# Run without installing
npx mqtt-tail

# Or install globally
npm install -g mqtt-tail

mqtt-tail [options] [topics...]

Topics default to # (all) when omitted. MQTT wildcards are fully supported:

• + matches a single level: sensors/+/temp
• # matches multiple levels: sensors/#

# Watch everything on localhost
mqtt-tail

# Single topic
mqtt-tail sensors/temperature

# Multiple topics with wildcards
mqtt-tail "sensors/+" "control/#"

# Remote broker with TLS and auth
mqtt-tail -H mqtt.example.com -p 8883 --tls -u alice -P secret "sensors/#"

# Filter by topic regex
mqtt-tail -f "temperature|humidity" "#"

# Filter by payload content
mqtt-tail --payload-filter "error" "logs/#"

# Exit after 20 messages
mqtt-tail -n 20 "#"

# One line per message (good for grepping)
mqtt-tail --compact "#"

# Pipe to jq
mqtt-tail --output-json "#" | jq '.payload'
mqtt-tail --output-json "sensors/#" | jq 'select(.topic | test("temp")) | .payload.value'

# Skip retained messages, show metadata
mqtt-tail --no-retained --verbose "#"

# CI / scripting (no colors, no timestamps)
mqtt-tail --no-color --no-timestamp --raw "#"

Default — pretty-printed, syntax-highlighted JSON, colored topics:

16:42:03.112 │ sensors/temperature
{
  "value": 23.5,
  "unit": "C"
}

--compact — one line per message:

16:42:03.112 │ sensors/temperature  {"value":23.5,"unit":"C"}

--output-json — newline-delimited JSON for scripting:

{"timestamp":"2024-01-15T16:42:03.112Z","topic":"sensors/temperature","payload":{"value":23.5},"qos":0,"retain":false,"size":28}

--raw — no formatting:

sensors/temperature {"value":23.5,"unit":"C"}

Options are resolved in this order (highest priority first):

1. CLI flags
2. process.env — shell environment variables
3. .env file — in the current working directory
4. ~/.mqtttailrc.json — global user config file

This means you can configure a broker once and forget about it, while still being able to override any value inline.

On first run (no broker config found), mqtt-tail starts an interactive setup wizard that asks for your broker host, port, credentials, and TLS settings, then saves them to ~/.mqtttailrc.json. Skip it by passing connection flags directly or by pre-creating the config file.

Config is read from your home directory and environment, not from the npx temp cache, so it works transparently with npx:

# One-time setup
echo '{"host":"mqtt.example.com","username":"alice","password":"secret"}' > ~/.mqtttailrc.json

# From now on, just run
npx mqtt-tail sensors/#

Place a .env in your current directory for project-specific settings:

MQTT_HOST=mqtt.example.com
MQTT_PORT=8883
MQTT_TLS=true
MQTT_USERNAME=alice
MQTT_PASSWORD=secret

Then run from that directory:

npx mqtt-tail sensors/#

Add .env to your .gitignore to keep credentials out of version control.

Useful for CI/CD, Docker, or one-off overrides:

MQTT_HOST=broker.example.com MQTT_USERNAME=alice MQTT_PASSWORD=secret npx mqtt-tail "#"

mqtt-tail searches the following locations in order:

1. ~/.mqtttailrc.json
2. ~/.mqtttailrc
3. .mqtttailrc.json in the current directory

Override the path with --config <file>.

{
  "host": "mqtt.example.com",
  "port": 8883,
  "tls": true,
  "username": "alice",
  "password": "secret"
}

mqtt-tail can also be used as a library inside your own Node.js programs.

import { subscribe } from 'mqtt-tail'

for await (const { topic, payload } of subscribe('sensors/#', { host: 'mqtt.example.com' })) {
  console.log(topic, payload.toString())
}

Returns an async generator that yields { topic, payload, packet } for each matched message. The connection closes and the loop ends automatically when count is reached, or when you break.

Config is loaded automatically from ~/.mqtttailrc.json / .env; opts overrides it. An error is thrown if the connection drops — no silent reconnection.

• Node.js >= 18

MIT

Built with Claude Code.