{"id":35402839,"url":"https://github.com/srcfl/mqtop","last_synced_at":"2026-01-21T11:01:04.073Z","repository":{"id":331329063,"uuid":"1122857561","full_name":"srcfl/mqtop","owner":"srcfl","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-18T16:27:52.000Z","size":238,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-19T00:54:41.515Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/srcfl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-25T17:08:06.000Z","updated_at":"2026-01-18T16:27:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/srcfl/mqtop","commit_stats":null,"previous_names":["srcfl/mqtop"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/srcfl/mqtop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srcfl%2Fmqtop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srcfl%2Fmqtop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srcfl%2Fmqtop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srcfl%2Fmqtop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srcfl","download_url":"https://codeload.github.com/srcfl/mqtop/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srcfl%2Fmqtop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28632237,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-02T11:56:41.833Z","updated_at":"2026-01-21T11:01:04.056Z","avatar_url":"https://github.com/srcfl.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mqtop\n\nA high-performance MQTT explorer TUI built in Rust by Sourceful Energy. Like htop for your MQTT broker - designed to handle high-throughput IoT telemetry streams.\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ mqtop │ ● Connected │ Topics: 436 │ Msgs: 12.5k (219/s) │ 5m │\n├─────────────────┬───────────────────────────────┬───────────────────────────┤\n│ Topics          │ Messages                      │ Stats                     │\n│                 │                               │                           │\n│ ▼ sensors       │ sensors/device-001/temp       │ Connection                │\n│   ▼ device-001  │                               │   Status: Connected       │\n│     ▶ temp      │ {                             │   Host: mqtt:8883         │\n│   ★ device-002  │   \"timestamp\": 1703...        │                           │\n│ ▶ metrics       │   \"value\": 23.5,              │ Messages                  │\n│ ▶ status        │   \"unit\": \"celsius\"           │   Total: 12.5k            │\n│                 │ }                             │   Rate: 219.2/s           │\n│                 │                               │                           │\n│                 │                               │ Device Health             │\n│                 │                               │   ● 12 healthy  ● 2 warn  │\n│                 │                               │                           │\n│                 │                               │ Tracked Metrics           │\n│                 │                               │   value: 23.5             │\n│                 │                               │   ▃▄▅▆▅▄▃▄▅▆▇▆▅▄▃▄▅▆▇█   │\n└─────────────────┴───────────────────────────────┴───────────────────────────┘\n q:Quit /:Search f:Filter s:Star y:Copy m:Track ?:Help\n```\n\n## Features\n\n- **Real-time MQTT streaming** - Subscribe to any topic pattern, handles 1000+ msg/sec\n- **Hierarchical topic tree** - Collapsible tree view with configurable color coding\n- **Device health monitoring** - Auto-tracks device activity and health status\n- **Metric tracking with sparklines** - Track numeric fields over time with live graphs\n- **MQTT wildcard filters** - Filter topics using `+` and `#` patterns\n- **Latency monitoring** - Track message delays and jitter\n- **Starred topics** - Bookmark important topics with persistence\n- **Publish bookmarks** - Save publish presets for quick one-click testing\n- **MQTT publishing** - Publish messages directly from the TUI with QoS and retain options\n- **Clipboard support** - Copy topics and payloads\n- **JSON syntax highlighting** - Pretty-printed payload inspection\n- **Vim-style navigation** - `hjkl`, arrows, and more\n- **Resilient connection** - Auto-reconnect with exponential backoff\n\n## Installation\n\n### Quick Install (Recommended)\n\n**macOS / Linux:**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/srcfl/mqtop/master/install.sh | bash\n```\n\n**Homebrew (macOS/Linux):**\n```bash\nbrew tap srcfl/tap\nbrew install mqtop\n```\n\n### Pre-built binaries\n\nDownload from [GitHub Releases](https://github.com/srcfl/mqtop/releases):\n\n| Platform | Download |\n|----------|----------|\n| macOS (Apple Silicon) | `mqtop-macos-arm64` |\n| macOS (Intel) | `mqtop-macos-x64` |\n| Linux (x64) | `mqtop-linux-x64` |\n| Linux (ARM64/Raspberry Pi) | `mqtop-linux-arm64` |\n| Windows | `mqtop-windows-x64.exe` |\n\n```bash\n# macOS/Linux: Make executable after download\nchmod +x mqtop-*\n\n# macOS: Remove quarantine (if you get a security warning)\nxattr -cr ./mqtop-*\n\n./mqtop-macos-arm64 --help\n```\n\n### Build from source\n\nRequires Rust 1.70+:\n\n```bash\ngit clone https://github.com/srcfl/mqtop.git\ncd mqtop\ncargo build --release\n```\n\nBinary will be at `target/release/mqtop` (3MB).\n\n## Quick Start\n\n### 1. Create a config file\n\nmqtop looks for configuration in this order:\n1. Path specified with `-c/--config`\n2. `./config.toml` in current directory\n3. `~/.config/mqtop/config.toml` (recommended for global install)\n\n```bash\n# Quick interactive setup\n./mqtop --setup\n\n# Or for global config (recommended)\nmkdir -p ~/.config/mqtop\ncp config.toml.example ~/.config/mqtop/config.toml\n# Edit with your MQTT credentials\n\n# Or for project-specific config\ncp config.toml.example config.toml\n```\n\n### 2. Or use command-line arguments\n\n```bash\n# With token passed via CLI\n./mqtop --host mqtt.example.com --port 8883 --tls --client-id mydevice --token \"your-jwt-token\"\n\n# Subscribe to specific topics\n./mqtop -c config.toml --topic \"sensors/#\"\n```\n\n### 3. Run it\n\n```bash\n./mqtop\n```\n\n## Configuration\n\nCreate `config.toml` in `~/.config/mqtop/` or your working directory:\n\n```toml\n[mqtt]\nactive_server = \"default\"\n\n[[mqtt.servers]]\nname = \"default\"\nhost = \"mqtt.example.com\"\nport = 8883\nuse_tls = true\nclient_id = \"mqtop-explorer\"\ntoken = \"your-jwt-token\"           # Stored in config\nsubscribe_topic = \"#\"              # Subscribe to all topics\nkeep_alive_secs = 30\n\n[ui]\nmessage_buffer_size = 100          # Messages kept per topic\nstats_window_secs = 10             # Window for rate calculations\ntick_rate_ms = 100                 # UI refresh rate\n\n# Optional: Custom topic highlighting\n[[ui.topic_colors]]\npattern = \"sensors\"\ncolor = \"cyan\"\n\n[[ui.topic_colors]]\npattern = \"alerts\"\ncolor = \"red\"\n\n# Optional: Count topics by category in Stats panel\n[[ui.topic_categories]]\nlabel = \"Sensors\"\npattern = \"sensors\"\ncolor = \"cyan\"\n\n[[ui.topic_categories]]\nlabel = \"Alerts\"\npattern = \"alerts\"\ncolor = \"red\"\n```\n\n### CLI Options\n\n```\nUsage: mqtop [OPTIONS]\n\nOptions:\n  -c, --config \u003cFILE\u003e      Config file path [default: ~/.config/mqtop/config.toml]\n      --host \u003cHOST\u003e        MQTT broker host (overrides config)\n      --port \u003cPORT\u003e        MQTT broker port (overrides config)\n      --client-id \u003cID\u003e     Client ID (overrides config)\n  -u, --username \u003cUSER\u003e    Username (defaults to client_id)\n      --token \u003cTOKEN\u003e      Token (overrides config)\n  -t, --topic \u003cTOPIC\u003e      Subscribe topic (overrides config)\n      --tls                Enable TLS\n      --setup              Run interactive config wizard\n      --list-backups       List config backups\n      --rollback \u003cINDEX\u003e   Restore config from backup (1 = newest)\n  -d, --debug              Enable debug logging to mqtop.log\n  -h, --help               Print help\n  -V, --version            Print version\n```\n\n## Usage Guide\n\n### Navigation\n\n| Key | Action |\n|-----|--------|\n| `Tab` | Switch between panels (Topics → Messages → Stats) |\n| `1` `2` `3` | Jump to panel directly |\n| `↑` `↓` or `j` `k` | Move up/down |\n| `←` `→` or `h` `l` | Collapse/expand or move into child |\n| `H` `L` | Collapse/expand full branch |\n| `Enter` | Toggle expand/collapse |\n| `PgUp` `PgDn` | Page up/down |\n| `g` `G` | Go to top/bottom |\n\nOn smaller terminals, mqtop automatically switches to 2-panel or 1-panel layouts.\n\n### Search \u0026 Filter\n\n| Key | Action |\n|-----|--------|\n| `/` | Open fuzzy search |\n| `PgUp` `PgDn` | Scroll search results |\n| `f` | Set topic filter (MQTT wildcards) |\n| `F` | Clear topic filter |\n| `*` | Toggle starred-only view |\n| `Esc` | Cancel/close overlay |\n| `S` | Open server manager |\n\n**Filter examples:**\n- `sensors/#` - All sensor topics\n- `sensors/+/temperature` - Temperature from any device\n- `building/+/floor/#` - All topics under any floor\n\n### Topic Management\n\n| Key | Action |\n|-----|--------|\n| `s` | Star/unstar current topic |\n| `y` | Copy topic path to clipboard |\n| `Y` | Copy payload to clipboard |\n\n### Server Manager\n\n| Key | Action |\n|-----|--------|\n| `S` | Open server manager |\n| `Enter` | Edit server |\n| `a` | Add server |\n| `d` | Delete server |\n| `Space` | Activate server |\n| `w` | Save config |\n| `Esc` | Close manager |\n\n### Server Edit\n\n| Key | Action |\n|-----|--------|\n| `Tab` `Shift+Tab` | Next/previous field |\n| `←` `→` `Home` `End` | Move cursor in field |\n| `Backspace` `Del` | Delete characters |\n| `Space` | Toggle TLS |\n| `Enter` | Save changes |\n| `Esc` | Cancel edit |\n\n### Publishing Messages\n\nmqtop allows you to publish MQTT messages directly from the TUI, perfect for testing and debugging.\n\n| Key | Action |\n|-----|--------|\n| `P` | Open publish dialog |\n| `Ctrl+P` | Copy current message to publish dialog |\n| `Tab` `Shift+Tab` | Navigate between fields |\n| `Space` | Toggle QoS (0/1/2) or Retain on/off |\n| `0` `1` `2` | Set QoS directly |\n| `Ctrl+S` | Save as bookmark |\n| `Enter` | Publish message |\n| `Esc` | Cancel |\n\n**Publish Dialog Fields:**\n- **Topic** - MQTT topic to publish to\n- **Payload** - Message content (supports multi-line)\n- **QoS** - Quality of Service (0=At most once, 1=At least once, 2=Exactly once)\n- **Retain** - Whether the broker should retain the message\n\n### Bookmarks (Publish Presets)\n\nSave frequently-used publish settings as bookmarks for quick one-click publishing. Perfect for:\n- Testing device commands\n- Sending alert triggers\n- Debugging with specific payloads\n- Rapid-fire testing scenarios\n\n| Key | Action |\n|-----|--------|\n| `B` | Open bookmark manager |\n| `Enter` | **Quick publish** selected bookmark (stays open for rapid testing) |\n| `a` | Add new bookmark |\n| `e` | Edit selected bookmark |\n| `d` | Delete selected bookmark |\n| `↑` `↓` or `j` `k` | Navigate bookmarks |\n| `Esc` | Close bookmark manager |\n\n**Bookmark Fields:**\n- **Name** - Display name (e.g., \"Temperature Alert\")\n- **Category** - Optional grouping (e.g., \"testing\", \"alerts\") - bookmarks are grouped by category\n- **Topic** - MQTT topic\n- **Payload** - Default payload content\n- **QoS** - Quality of Service level\n- **Retain** - Retain flag\n\n**Quick Workflows:**\n\n1. **Save from Publish Dialog:**\n   - Press `P` to open publish dialog\n   - Fill in topic, payload, QoS, retain\n   - Press `Ctrl+S` to save as bookmark\n   - Edit the name and category, then `Enter` to save\n\n2. **Rapid-Fire Testing:**\n   - Press `B` to open bookmark manager\n   - Navigate to desired preset\n   - Press `Enter` to publish (manager stays open)\n   - Repeat for rapid testing\n\n3. **Copy \u0026 Modify:**\n   - Select a topic in the tree\n   - Press `Ctrl+P` to copy to publish dialog\n   - Modify payload as needed\n   - Press `Ctrl+S` to save as bookmark for future use\n\nBookmarks are persisted in `~/.config/mqtop/userdata.json` and survive restarts.\n\n### Metrics \u0026 Display\n\n| Key | Action |\n|-----|--------|\n| `m` | Track metric from current message (opens field selector) |\n| `p` | Cycle payload mode (Auto → Raw → Hex → JSON) |\n| `c` | Clear statistics |\n\n### General\n\n| Key | Action |\n|-----|--------|\n| `?` | Toggle help overlay |\n| `q` or `Ctrl+C` | Quit |\n\n## Panels\n\n### Topic Tree (Left)\n\nDisplays all discovered topics in a hierarchical tree. Topic colors are configurable via `[[ui.topic_colors]]` in your config file. UUIDs and IDs are automatically shown in gray.\n\nA `★` indicator shows starred topics.\n\n### Messages (Center)\n\nShows messages for the selected topic with:\n- Timestamp\n- JSON syntax highlighting (keys, strings, numbers, booleans)\n- Multiple display modes (Auto, Raw, Hex, JSON)\n\n### Stats (Right)\n\nReal-time statistics including:\n- Connection status\n- Message count and rate\n- Data throughput\n- **Latency metrics** - Message delays, inter-arrival times, jitter\n- **Topic categories** - Configurable counters via `[[ui.topic_categories]]`\n- Device health summary\n- Tracked metrics with sparklines\n\n## Data Persistence\n\nmqtop stores data in `~/.config/mqtop/`:\n- `config.toml` - Configuration file (optional, can also use `./config.toml`)\n- `backups/` - Rolling config backups (last 5)\n- `userdata.json` - Starred topics, tracked metrics, and publish bookmarks (auto-saved)\n\n## Troubleshooting\n\n### Connection issues\n\nEnable debug logging:\n```bash\n./mqtop --debug\ntail -f mqtop.log\n```\n\n### Large payloads\n\nmqtop supports payloads up to 1MB. If you see truncated messages, check the source.\n\n### High CPU usage\n\nReduce tick rate in config:\n```toml\n[ui]\ntick_rate_ms = 200  # Default is 100\n```\n\n## Development\n\n```bash\n# Run tests\ncargo test\n\n# Run with debug output\ncargo run -- --debug\n\n# Build release\ncargo build --release\n```\n\n## Author\n\nCreated by **Fredrik Ahlgren** ([@frahlg](https://github.com/frahlg) on GitHub, [@frahlg](https://x.com/frahlg) on X)\nCEO of [Sourceful Labs AB](https://sourceful.energy) (Sourceful Energy)\n\nCo-authored with [Claude Code](https://claude.com/claude-code).\n\n## License\n\nMIT License - Sourceful Energy 2024\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Submit a pull request\n\nFor bugs and feature requests, open an issue on GitHub.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrcfl%2Fmqtop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrcfl%2Fmqtop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrcfl%2Fmqtop/lists"}