Skip to content

MQTT CLI: Smart, Compact, Open Source

by Anja Helmbrecht-Schaar
14 min read

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

MQTT Features and CLI Features Content Table

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
or
sudo 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.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

$ 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: false

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

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

myTestClient> dis
mqtt> exit

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:

mqtt.host=broker.hivemq.com

Unless 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_1

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

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 client

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

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

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

Subscribe Examples

The subscribe operation can be done analog to the publish.

Example: Simple Subscribe to topics

mqtt sub -i myClient -t test1 -t test2

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.

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.

  • Contact Anja Helmbrecht-Schaar via e-mail
HiveMQ logo
Review HiveMQ on G2