MQTT CLI: Smart, Compact, Open Source
This is the MQTT CLI tool you’ve been waiting for
At HiveMQ we have worked with many customers to develop and test their MQTT deployments. One thing we have found is the need for a command line tool to quickly generate MQTT test clients to test the connections between clients and an MQTT broker. Over the years, we have used various utilities developed by the open source community but none seem to have all the features we needed.
For this reason, we are happy to announce a new open source tool, called MQTT CLI, that provides a command line interface (CLI) to interact with an MQTT broker. The new tool provides two key features: 1) a SHELL mode that allows you to start multiple MQTT clients in parallel and supports connection handling and provides unix-like shell features, such as color-highlighting, tab-completion, command-history, and password masking. 2) support for both MQTT pub and sub commands so you have one command line for all the key MQTT operations.
We are making the MQTT CLI available in open source under the Apache License 2.0. The tool supports MQTT 3.1.1 and MQTT 5 and can be used with any MQTT broker. Our hope is to see this tool being embraced by the entire MQTT community, not just HiveMQ users. We have tested it with the HiveMQ public broker and the Mosquitto public broker. Feel free to try it out and let us know what you think.
Short info
| Purpose | Provide a compact command line interface (CLI) for MQTT 3.1.1 and MQTT 5 clients that supports interactive command modes. |
|---|---|
| License | Apache License 2.0 |
| Website | https://github.com/hivemq/mqtt-cli |
| API Style | Blocking |
Description
The MQTT CLI is an open-source Java MQTT client tool that enables you to interact quickly and easily with any MQTT Broker in various ways. The CLI gives you a single compact tool for the most important client operations (PUBLISH and SUBSCRIBE). The CLI tool also provides an interactive and comfortable SHELL mode that enables you to work with multiple MQTT clients in parallel and supports connection handling. The MQTT CLI supports all MQTT features for MQTT Version 5 & 3.1.1. The tool uses the HiveMQ-MQTT client library, which is a fast, low-overhead, high-throughput, and modern MQTT library written in Java.The MQTT CLI comes in various binary packages that can be downloaded from the documentation homepage on GitHub.
Key MQTT & CMD Features
Usage
The following is a quick summary of how to use the MQTT CLI. The full documentation with many examples and explanations can be found here.
Installation
The MQTT CLI is available for MAC-OS, Windows, and various Linux distributions.
Download the executable from the latest release or simply clone from GitHub into your home folder.
Install on Mac-OS
This example shows you how to install the MQTT CLI on Mac-OS with homebrew.
$ brew tap hivemq/mqtt-cli
$ brew install mqtt-cli
==> Installing mqtt-cli from hivemq/mqtt-cli
brew /usr/local/Cellar/mqtt-cli/4.25.0: 5 files, ... built in 2 seconds
$ mqtt <command>These commands install the MQTT CLI and add an .mqtt-cli/ subfolder to your home folder that contains the config.properties and a log folder.
Install on a Windows system
Download the Windows Zip-file here and extract it in your preferred location.
To execute MQTT CLI simply open the Windows Command Prompt with Win + R and execute cmd.
Navigate into the extracted MQTT CLI folder and execute the command: mqtt-cli.exe
To quick start the shell simply double-click the command: mqtt-cli-shell.exe
Install on Debian/Ubuntu Systems
If you are using a *nix operating system which operates with debian packages you can download the MQTT CLI debian package from the releases page here via wget or curl and install the package with:sudo dpkg -i
orsudo apt install.
$ wget
https://github.com/hivemq/mqtt-cli/releases/download/v4.25.0/mqtt-cli-4.25.0.deb
$ sudo apt install ./mqtt-cli-4.25.0.debInstall as RPM Package
For Red Hat, Fedora, Mandriva, OpenSuse, CentOS distributions you can use the rpm package provided at releases page here. The preferred way is to install the package via the yum package manager. To install the package simply execute:
$ sudo yum install -y
https://github.com/hivemq/mqtt-cli/releases/download/v4.25.0/mqtt-cli-4.25.0.rpmStart
The easiest way to start the CLI is to type mqtt on your console.
See also $ mqtt --help.
$ mqtt --help outputs information on how to use the MQTT CLI:
Usage: mqtt [-hV] { pub | sub | shell }
MQTT Command Line Interpreter.
Options:
-h, --help Show this help message and exit.
-V, --version Print version information and exit.
Commands:
sh, shell Starts MQTT CLI in shell mode,
to enable interactive mode with
further sub commands.
sub, subscribe Subscribe an mqtt client to a list of topics
pub, publish Publish a message to a list of topicsSynopsis
$ mqtt [flags] [METHOD] [OPTION [OPTION]]
Supported commands at start
shell command
mqtt publish
mqtt subscribe
Shell Mode
The shell mode starts the MQTT CLI as an interactive shell session. Shell mode provides a comfortable unix-like terminal for handling console input and output.
In shell mode, various familiar shell features are available for the MQTT operations:
color-highlighting,
tab-completion,
command-history,
password-masking.
The shell mode gives you a client context for the MQTT clients that are currently connected. You can connect MQTT clients, work with the clients to publish, subscribe, unsubscribe, or list all clients to disconnect all or a few of your MQTT clients. Methods such as Connect and Disconnect switch the current context of the shell. Commands such as Publish and Subscribe always relate to the client context that is currently active.
You can start the interactive shell with a simple command in your terminal:
$ mqtt shell
Example
$ mqtt shell
--> starts the shell and informs you about the default broker configuration, port, and the location of the log file.Example: Connect an MQTT client
mqtt> con -i myTestClient
-> creates an MQTT connection for the MQTT client that is uniquely defined by the Identifier #myTestClient and the defaulthost (localhost) the broker address.
-> creates the MQTT context and the shell switch to new client context
myTestClient>NOTE: If you want to use another host and port for the broker, you can set the parameter directly in the command or adapt the default settings from the config.properties. If you don’t have a local broker installed, you can use the broker.hivemq.com, test.mosquitto.org or mqtt.eclipse.org or any public broker for testing purposes.
Example: Subscribe to the topic and publish a message
myTestClient > sub -t test
myTestClient > pub -t test -m 'A message'
-> the myTestClient gets the message 'A message'Example: Switch back to the shell and list all information on the MQTT clients
myTestClient> exit
mqtt> ls -at
-> Created-At: 2019-09-17T16:25:49
Client-ID: myTestClient
Server-Address: broker.hivemq.com:1883
MQTT version: MQTT_5_0
SSL: falseExample: Switch back to the client to publish a retained message with QoS 1
mqtt> switch myTestClient
myTestClient> pub -t test -m 'A further message' -q 1 -r
-> the myTestClient gets 'A further message' with QoS 1 and sends a PUBACKExample: Disconnect the client, leave the context, and exit the shell
myTestClient> dis
mqtt> exitSummary of shell-mode usage:
Connect a couple of MQTT clients with different versions to different broker addresses.
Work in and outside the context of an MQTT client.
Switch from one client context to another client context.
Leave the context of a client without disconnecting.
List all topics to which a client is subscribed.
List all active clients.
Disconnect clients.
Modify default configuration settings
The MQTT CLI works with a default configuration of commonly used values. The first time the CLI successfully executes, the default configuration file is generated and stored in the .mqtt-cli/ subfolder of your home folder.
Configuration example
# default host and port for broker address if not specified in the command
mqtt.port=1883
mqtt.host=localhost
# default mqtt version if not specified in the command
mqtt.version=5
# default prefix for MQTT clients identifier
client.prefix=hmqClient
# logging setting
debug.level.shell=VERBOSE
debug.logfile.path=/<home>/.mqtt-cli/logs/You can adjust the default settings to suit your individual needs.
Example of how to set the HiveMQ public broker in the config.properties:
mqtt.host=broker.hivemq.comUnless you override the default setting with a parameter in the command, an MQTT client uses the default.
Restart the shell and try out.
$ mqtt shell
mqtt> con -i myTestClient1
-> creates an MQTT 5 client and connects to broker.hivemq.com:1883
mqtt> con -h localhost -p 1884 -V 3
-> creates an MQTT 3 client with a default identifier and connects to localhost:1884
..
mqtt> ls -at
->
Created-At:
2019-09-17T16:25:49
2019-09-17T16:25:49
Client-ID:
myTestClient1
hmqClient-1dad42342
Server-Address:
broker.hivemq.com:1883
localhost:1884
MQTT version:
MQTT_5_0
MQTT_3_1_1Simple Command Modes
Simple publish and subscribe operations with the MQTT CLI always include the following steps:
Create an MQTT client
Connect to the broker address
Do the MQTT operation
Receive acknowledgment of the MQTT operation
For PUBLISH - disconnect the MQTT client
Publish Examples
Example: Simple Publish of a message to a topic
mqtt pub -t test -m "Hello"
-> creates an MQTT 5 client and connects to the default broker address
-> publishes a "Hello" message to the test topic and receives a PUBACK
-> disconnects the client
Example: Simple Publish of a message to several topics
mqtt pub -t test1 -t test2 -m "Hello Test1 and 2"
-> creates an MQTT 5 client and connects to the default broker address
-> publishes a "Hello Test1 and 2" to the test1 and test2 topics and receives two PUBACK
-> disconnects the clientExample: Simple Publish to a broker with port 1884
mqtt pub -t test1 -m "Hello" -p 1884
-> creates an MQTT 5 client and connects to default broker host and port 1884
-> publishes a "Hello" to the test1 topic and receives a PUBACK
-> disconnects the clientExample: Publish with username and blank password in which the user is prompted to input the password on the console
mqtt pub -t test1 -m "Hello" -u super -P
Enter value for --password (The password for authentication): ******
-> creates an MQTT 5 client and connects to default broker address
-> publishes a "Hello" to the test1 topic and receives a PUBACK
-> disconnects the clientExample: Publish with MQTT 5 user properties and debug mode.
mqtt pub -i myClient -t test -m "Hello" -up key1=value1 --debug
Client myClient: sending CONNECT
Client myClient: received CONNACK SUCCESS
Client myClient: sending PUBLISH: (Topic: test, QoS AT_MOST_ONCE, Message: 'Hello')
Client myClient: received PUBACK: 'Hello' for PUBLISH to Topic: testSubscribe Examples
The subscribe operation can be done analog to the publish.
Example: Simple Subscribe to topics
mqtt sub -i myClient -t test1 -t test2Example: Subscribe to several topics and connect with MQTT 5 user properties and debug mode. The Client stays to consume incoming PUBLISHES that are displayed in the console.
mqtt sub -i myClient -t test1 -t test2 -up key1=value1 --debug
Client myClient: sending CONNECT
Client myClient: received CONNACK SUCCESS
Client myClient: sending SUBSCRIBE: (Topic: test1, QoS: AT_MOST_ONCE)
Client myClient: sending SUBSCRIBE: (Topic: test2, QoS: AT_MOST_ONCE)
Client myClient: received SUBACK: [GRANTED_QOS_0]
Client myClient: received SUBACK: [GRANTED_QOS_0]
Hello myClient
Client myClient: received PUBLISH: (Topic: test1, Message: 'Hello myClient')Logging
When you run shell mode, all MQTT commands and actions are logged to a daily log file. The log level and the location are defined in the config.properties and can be modified to suit your needs.
The VERBOSE logging mode provides detailed and fine grained information about each operation, MQTT message, and acknowledgement. Additionally, any errors that occur are logged with a full stack trace.
To get more information on what happens during the MQTT operation, the simple publish and subscribe commands can be started with a debug flag.
Conclusion
The MQTT CLI is an open source project under Apache 2 license and hosted by HiveMQ. With the MQTT CLI you have a smart and compact tool that helps you especially during the development and test phase, to easily and quickly execute MQTT operations at the command line level. Distributions for the most common operating systems are available. Try out our smart tool and download from Github.
Anja Helmbrecht-Schaar
Anja Helmbrecht-Schaar was previously a Senior MQTT & Architectural Consultant at HiveMQ. Anja supported customers with the application-specific implementation of HiveMQ extensions as well as the introduction and integration of HiveMQ into their system landscape. She is an MQTT expert who has held many workshops around the protocol and the HieMQ broker.
