Tooling & Control

TinyMQ ships two first-class control interfaces: an embedded web dashboard at /dashboard and a native CLI binary called tmq. Both connect to the broker over HTTP and require no special authentication.

---

The Interactive Dashboard

Navigate to http://localhost:7800/dashboard in any browser while the broker is running.

Dashboard Overview

The dashboard renders a live metrics grid and a sortable topic table. All logic runs in Vanilla JS — no React, no Vue, no bundle size tax.

Metrics Grid:

Card	Description
Uptime	How long the broker process has been running
Active Queues/Topics	Total number of topics with at least one message or waiting consumer
Messages in RAM	Total messages held across all queues
Webhooks	Total registered webhook endpoints
Broker Memory	Go runtime runtime.MemStats.Alloc — actual heap in use

Topic Table Columns:

Column	Description
Queue / Topic Name	Topic identifier. DLQ topics shown with a red DLQ badge; webhook-enabled topics with an orange Webhook badge
Waiting Consumers	Number of long-polling consumers currently blocking on this topic
Messages in RAM	Current message count in the queue
Actions	Inline buttons: Publish, Consume (Pop), 👁️ Peek

Auto-Refresh

Toggle Auto-Refresh in the top control bar. When enabled, the page reloads every 3 seconds. The setting is persisted in localStorage so it survives page reloads.

Auto-Refresh pauses automatically when any modal (Publish, Consume, Peek) is open to prevent the page from refreshing while you're reading output.

Publish via Dashboard

1. Click the Publish button on any topic row
2. Enter a JSON payload in the modal textarea (pre-filled with a sample)
3. Click Send Message

The broker receives the payload via POST /api/queues/publish.

Consume (Pop) via Dashboard

1. Click the Consume (Pop) button on any topic row
2. The modal displays the message ID, timestamp, and decoded payload
3. The message is immediately acknowledged and removed from the queue

Returns 204 No Content if the queue is empty.

Peek via Dashboard (Non-Destructive Inspection)

1. Click 👁️ Peek on any topic row
2. The modal shows up to 10 messages without removing them from RAM

Peek reads from GET /api/queues/peek?queue={name} and calls broker.Peek() internally — a pure read with no side effects, no ACKs, no WAL writes.

---

The tmq CLI

tmq is a terminal-based control panel for TinyMQ. It connects to the broker over HTTP and presents colored, tabwriter-aligned output.

Installation

Download from GitHub Releases or install via Go:

go install github.com/x-name15/tinymq/cmd/tmq@latest

Configuration

Set TINYMQ_URL to point at a non-local broker:

export TINYMQ_URL=http://192.168.1.100:7800

Default is http://localhost:7800.

---

Command Reference

tmq status / tmq list

Displays a formatted table of all active topics, their message counts, waiting consumer count, type, and webhook status.

tmq status

Example output:

STATE OF 🍃 TINYMQ (http://localhost:7800)

QUEUE / TOPIC NAME    MESSAGES (RAM)    WAITING WORKERS    TYPE        WEBHOOKS
orders.eu             12                0                  Standard    No
orders.us             0                 3                  Standard    No
notifications         0                 0                  Standard    Yes
orders.eu.dlq         2                 0                  DLQ         No

tmq pub — Publish a Message

# Basic publish
tmq pub orders.eu '{"user_id": 42, "item": "laptop"}'

# With TTL (expire in 5 minutes)
tmq pub orders.eu '{"user_id": 42}' --ttl=5m

# With delivery delay
tmq pub notifications '{"msg": "hello"}' --delay=10s

# Broadcast to all waiting consumers
tmq pub cache.invalidate '{"entity": "product"}' --broadcast

Flags:

Flag	Type	Description
--ttl	duration	Time-To-Live (e.g., 30s, 5m, 1h)
--delay	duration	Delivery delay (e.g., 10s, 1m)
--broadcast	bool	Enable fan-out mode

tmq sub — Consume Messages

# Consume one message (auto-acknowledged)
tmq sub orders.eu

# Wait up to 10s for a message if queue is empty (long-polling)
tmq sub orders.eu --timeout=10s

# Consume a batch of 5 messages
tmq sub orders.eu --limit=5

# Consume without auto-acknowledging (manual ACK required)
tmq sub orders.eu --auto-ack=false

Flags:

Flag	Type	Default	Description
--timeout	duration	0s	Long-polling wait time
--limit	int	1	Number of messages to retrieve
--auto-ack	bool	true	Auto-acknowledge on consume

tmq peek — Inspect RAM (Non-Destructive)

Reads messages from the queue without removing them. Safe for debugging.

# Peek at the first 10 messages (default)
tmq peek orders.eu

# Peek at the first 3 messages
tmq peek orders.eu --limit=3

# Inspect a DLQ
tmq peek orders.eu.dlq

Example output:

PEEKING RAM OF 'orders.eu' (Showing first 3)

[1] ID: a1b2c3d4 | Attempts: 0 | 10:15:32
   {"user_id": 42, "item": "laptop"}

[2] ID: b2c3d4e5 | Attempts: 1 | 10:16:01
   {"user_id": 99, "item": "keyboard"}

[3] ID: c3d4e5f6 | Attempts: 0 | 10:16:45
   {"user_id": 7, "item": "monitor"}

tmq tail — Live Spy Mode

Continuously streams messages from a topic in real-time. Each message is printed as it arrives. Press Ctrl+C to exit.

tmq tail orders.eu

Output format:

Spy Mode: Listening to 'orders.eu' in real-time... (Ctrl+C to exit)
[10:22:01] a1b2c3d4 -> {"user_id": 42, "item": "laptop"}
[10:22:15] b2c3d4e5 -> {"user_id": 99, "item": "keyboard"}

warning

tmq tail uses auto_ack=true and consumes messages permanently. It is intended for debugging and development monitoring, not production observation. Use tmq peek for non-destructive inspection.

---

CLI Quick Reference

# Show all active queues
tmq status

# Publish with options
tmq pub <topic> <payload> [--ttl=duration] [--delay=duration] [--broadcast]

# Consume with options
tmq sub <topic> [--timeout=duration] [--limit=count] [--auto-ack=true/false]

# Non-destructive inspection
tmq peek <topic> [--limit=count]

# Real-time stream (consumes permanently)
tmq tail <topic>

# Help
tmq help