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

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

MQTT Features		CLI Features
MQTT 3.1.1		Shell mode with syntax highlighting, Cmd-History, ..
MQTT 5.0		Connect many MQTT clients
SSL/TLS		Context behavior
QoS 1		Clients overview
QoS 2		Configurable defaults
Reconnect Handling		Verbose logging

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

$ 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

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

$ 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.deb

Install 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.rpm

Start

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 topics

Synopsis

$ 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

Example: Connect an MQTT client

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

Example: Switch back to the shell and list all information on the MQTT clients

Example: Switch back to the client to publish a retained message with QoS 1

Example: Disconnect the client, leave the context, and exit the shell

Summary 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:

Unless you override the default setting with a parameter in the command, an MQTT client uses the default.

Simple 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

Example: Simple Publish of a message to several topics

Example: Simple Publish to a broker with port 1884

Example: Publish with username and blank password in which the user is prompted to input the password on the console

Example: Publish with MQTT 5 user properties and debug mode.

Subscribe Examples

The subscribe operation can be done analog to the publish.

Example: Simple Subscribe to topics

Example: 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.

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.

About Anja Helmbrecht-Schaar

Anja works as Senior MQTT & Architectural Consultant at HiveMQ. Anja supports customers with the application-specific implementation of HiveMQ extensions as well as the introduction and integration of HiveMQ into their system landscape.

Contact Anja