mqttv5-cli 0.11.2

Superior CLI tool for MQTT v5.0 - unified client and broker commands with ergonomic input design
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

# mqttv5 - MQTT v5.0 Command Line Interface

[![Crates.io](https://img.shields.io/crates/v/mqttv5-cli.svg)](https://crates.io/crates/mqttv5-cli)
[![Downloads](https://img.shields.io/crates/d/mqttv5-cli.svg)](https://crates.io/crates/mqttv5-cli)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](https://github.com/LabOverWire/mqtt-lib#license)

A unified MQTT v5.0 CLI tool with pub, sub, and broker commands.

## Features

- Single binary: pub, sub, and broker subcommands
- Interactive prompts for missing arguments
- Input validation with error messages and suggestions
- MQTT v5.0 protocol support
- Session management: Clean start, session expiry, and persistence
- Will message support: Last will and testament with delay and QoS options
- Automatic reconnection: Opt-in reconnection with exponential backoff
- Multi-transport: TCP, TLS, WebSocket, and QUIC support
- Cross-platform: Linux, macOS, and Windows

## Installation

```bash
cargo install mqttv5-cli
```

## Usage

### Publishing Messages

```bash
# Basic publish
mqttv5 pub --topic "sensors/temperature" --message "23.5°C"

# With QoS and retain
mqttv5 pub -t "sensors/temperature" -m "23.5°C" --qos 1 --retain

# Interactive mode (prompts for missing args)
mqttv5 pub
```

### Subscribing to Topics

```bash
# Basic subscribe
mqttv5 sub --topic "sensors/+"

# Verbose mode shows topic names
mqttv5 sub -t "sensors/#" --verbose

# Subscribe for specific message count
mqttv5 sub -t "test/topic" --count 5

# Session persistence and QoS
mqttv5 sub -t "data/#" --qos 2 --no-clean-start --session-expiry 3600

# Auto-reconnect on disconnect (opt-in)
mqttv5 sub -t "sensors/+" --auto-reconnect
```

### Running a Broker

```bash
# Start broker on default port
mqttv5 broker

# Custom port and bind address
mqttv5 broker --host 0.0.0.0:1883

# Interactive configuration
mqttv5 broker
```

## CLI Design

- Error messages with suggestions
- Prompts for missing required arguments
- Single binary for all MQTT operations
- Long flags with short aliases
- MQTT v5.0 support including properties and reason codes

### Connection Behavior

By default, the CLI exits immediately when the broker disconnects. This prevents duplicate topic takeover issues when clients reconnect with the same client ID.

Use `--auto-reconnect` to enable automatic reconnection with exponential backoff. When enabled:

- The library handles reconnection automatically
- Subscriptions are restored based on session state
- The client continues running until Ctrl+C or target message count reached

## Examples

### Publishing sensor data

```bash
mqttv5 pub -t "home/living-room/temperature" -m "22.5" --qos 1
```

### Monitoring all home sensors

```bash
mqttv5 sub -t "home/+/+" --verbose
```

### Testing with retained messages

```bash
mqttv5 pub -t "config/device1" -m '{"enabled": true}' --retain
```

### Advanced MQTT v5.0 Features

```bash
# Will messages for device monitoring
mqttv5 pub -t "sensors/data" -m "active" \
  --will-topic "sensors/status" --will-message "offline" --will-delay 5

# Authentication and session management
mqttv5 sub -t "secure/data" --username user1 --password secret \
  --no-clean-start --session-expiry 7200

# Custom keep-alive and transport options
mqttv5 pub -t "test/topic" -m "data" --keep-alive 120 \
  --url "mqtts://secure-broker:8883"

# WebSocket transport
mqttv5 pub --url "ws://broker:8080/mqtt" -t "test/websocket" -m "WebSocket message"
mqttv5 sub --url "wss://secure-broker:8443/mqtt" -t "test/+"

# QUIC transport (insecure mode for testing)
mqttv5 pub --url "quic://broker:14567" -t "test/quic" -m "QUIC message"
mqttv5 sub --url "quic://broker:14567" -t "test/+"

# QUIC transport with certificate verification
mqttv5 pub --url "quics://broker:14567" -t "test/quic" -m "Secure QUIC" --ca-cert ca.crt
mqttv5 sub --url "quics://broker:14567" -t "test/+" --insecure

# Message expiry and topic alias
mqttv5 pub -t "sensors/temp" -m "23.5" --message-expiry-interval 300 --topic-alias 1

# Subscription options (retain handling: 0=send, 1=send if new, 2=don't send)
mqttv5 sub -t "config/#" --retain-handling 2 --retain-as-published
```

## Environment Variables

- `MQTT_HOST`: Default broker host (default: localhost)
- `MQTT_PORT`: Default broker port (default: 1883)

## License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.