Get Started

After installing it, run mqttx on the terminal.

Quick Start

Connect

mqttx conn -h 'broker.emqx.io' -p 1883 -u 'admin' -P 'public'

Subscribe

mqttx sub -t 'hello' -h 'broker.emqx.io' -p 1883

Publish

# Publish a single message
mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 -m 'from MQTTX CLI'

# Publish multiple messages (multiline)
mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 -s -M

Benchmark

# Connect Benchmark
mqttx bench conn -c 5000

# Subscribe Benchmark
mqttx bench sub -c 5000 -t bench/%i

# Publish Benchmark
mqttx bench pub -c 5000 -t bench/%i

Simulate

# Specify a local built-in scenario and start the simulation
mqttx simulate -sc tesla -c 10

# Specify a scenario file and start the simulation
mqttx simulate -f <scenario file path> -c 10

# List the built-in scenarios
mqttx ls -sc

Version Check

mqttx check

Use

mqttx --help
OptionsDescription
-v, --versionOutput the version number
-h, --helpDisplay help for command
CommandDescription
checkCheck for updates
connCreate a connection and connect to MQTT Broker
pubPublish a message to a topic
subSubscribes to one or multiple topics
benchMQTT Benchmark in performance testing
simulateSimulate publishing scenario-specific MQTT messages

Connection

mqttx conn --help
OptionsDescription
-V, --mqtt-version <5/3.1.1/3.1>the MQTT version (default: 5)
-h, --hostname <HOST>the broker host (default: "localhost")
-p, --port <PORT>the broker port
-i, --client-id <ID>the client id
--no-cleanset the clean session flag to false (default: true)
-k, --keepalive <SEC>send a ping every SEC seconds (default: 30)
-u, --username <USER>the username
-P, --password <PASS>the password
-l, --protocol <PROTO>the protocol to use, mqtt, mqtts, ws, or wss (default: mqtt)
--path <PATH>the path of websocket (default: /mqtt)
--key <PATH>path to the key file
--cert <PATH>path to the cert file
--ca <PATH>path to the ca certificate
--insecuredo not verify the server certificate
--alpn <PROTO...>set one or multiple ALPN (Application Layer Protocol Negotiation) protocols
-rp, --reconnect-period <MILLISECONDS>interval between two reconnections, disable auto reconnect by setting to 0 (default: 1000ms)
--maximum-reconnect-times <NUMBER>the maximum reconnect times (default: 10)
-up, --user-properties <USERPROPERTIES...>the user properties of MQTT 5.0 (e.g. -up "name: mqttx cli")
-Wt, --will-topic <TOPIC>the will topic
-Wm, --will-message <BODY>the will message
-Wq, --will-qos <0/1/2>the will qos
-Wr, --will-retainsend a will retained message (default: false)
-Wd, --will-delay-interval <SECONDS>the will delay interval in seconds
-Wpf, --will-payload-format-indicatorwill message is UTF-8 encoded character data or not
-We, --will-message-expiry-interval <SECONDS>lifetime of the will message in seconds
-Wct, --will-content-type <CONTENTTYPE>description of the will message’s content
-Wrt, --will-response-topic <TOPIC>topic name for a response message
-Wcd, --will-correlation-data <DATA>correlation data for the response message
-Wup, --will-user-properties <USERPROPERTIES...>the user properties of will message
-se, --session-expiry-interval <SECONDS>the session expiry interval in seconds
--rcv-max, --receive-maximum <NUMBER>the receive maximum value
--maximum-packet-size <NUMBER>the maximum packet size the client is willing to accept
--topic-alias-maximum <NUMBER>the topic alias maximum value
--req-response-infothe client requests response information from the server
--no-req-problem-infothe client requests problem information from the server
--save [PATH]save the parameters to the local configuration file, which supports json and yaml format, default path is ./mqttx-cli-config.json
--config [PATH]load the parameters from the local configuration file, which supports json and yaml format, default path is ./mqttx-cli-config.json
--debugEnable debug mode for MQTT.js (default: false)
--helpdisplay help for conn command

Subscribe

mqttx sub --help
OptionsDescription
-V, --mqtt-version <5/3.1.1/3.1>the MQTT version (default: 5)
-h, --hostname <HOST>the broker host (default: "localhost")
-p, --port <PORT>the broker port
-i, --client-id <ID>the client id
-q, --qos <0/1/2>the QoS of the message (default: 0)
--no-cleanset the clean session flag to false (default: true)
-t, --topic <TOPIC>the message topic
-k, --keepalive <SEC>send a ping every SEC seconds (default: 30)
-u, --username <USER>the username
-P, --password <PASS>the password
-l, --protocol <PROTO>the protocol to use, mqtt, mqtts, ws, or wss (default: mqtt)
--path <PATH>the path of websocket (default: /mqtt)
-nl, --no_localthe no local MQTT 5.0 flag
-rap, --retain-as-publishedthe retain as published MQTT 5.0 flag
-rh, --retain-handling <0/1/2>the retain handling MQTT 5.0
--key <PATH>path to the key file
--cert <PATH>path to the cert file
--capath to the ca certificate
--insecuredo not verify the server certificate
--alpn <PROTO...>set one or multiple ALPN (Application Layer Protocol Negotiation) protocols
-rp, --reconnect-period <MILLISECONDS>interval between two reconnections, disable auto reconnect by setting to 0 (default: 1000ms)
--maximum-reconnect-times <NUMBER>the maximum reconnect times (default: 10)
-up, --user-properties <USERPROPERTIES...>the user properties of MQTT 5.0 (e.g. -up "name: mqttx cli")
-f, --format <TYPE>format the message body, support base64, json, hex and cbor
-v, --verboseprint the topic before the message
--output-mode <default/clean>choose between the default and clean mode, which outputs the complete MQTT packet data, allowing users to pipe the output as they wish
-Wt, --will-topic <TOPIC>the will topic
-Wm, --will-message <BODY>the will message
-Wq, --will-qos <0/1/2>the will qos
-Wr, --will-retainsend a will retained message (default: false)
-Wd, --will-delay-interval <SECONDS>the will delay interval in seconds
-Wpf, --will-payload-format-indicatorwill message is UTF-8 encoded character data or not
-We, --will-message-expiry-interval <SECONDS>lifetime of the will message in seconds
-Wct, --will-content-type <CONTENTTYPE>description of the will message’s content
-Wrt, --will-response-topic <TOPIC>topic name for a response message
-Wcd, --will-correlation-data <DATA>correlation data for the response message
-Wup, --will-user-properties <USERPROPERTIES...>the user properties of will message
-se, --session-expiry-interval <SECONDS>the session expiry interval in seconds
-si, --subscription-identifier <NUMBER>the identifier of the subscription
--rcv-max, --receive-maximum <NUMBER>the receive maximum value
--maximum-packet-size <NUMBER>the maximum packet size the client is willing to accept
--topic-alias-maximum <NUMBER>the topic alias maximum value
--req-response-infothe client requests response information from the server
--no-req-problem-infothe client requests problem information from the server
-Cup, --conn-user-properties <USERPROPERTIES...>the connect user properties of MQTT 5.0 (e.g. -Cup "name: mqttx cli")
--save [PATH]save the parameters to the local configuration file, which supports json and yaml format, default path is ./mqttx-cli-config.json
--config [PATH]load the parameters from the local configuration file, which supports json and yaml format, default path is ./mqttx-cli-config.json
--helpdisplay help for sub command
-Pp, --protobuf-path <PATH>the path to the .proto file that defines the message format for Protocol Buffers (protobuf)
-Pmn, --protobuf-message-name <NAME>the name of the protobuf message type (must exist in the .proto file)
--debugEnable debug mode for MQTT.js (default: false)

Note: If you are subscribing to topics with a $ prefix, such as shared subscriptions like $share/test/test, you need to add quotes around "$share/test/test". $share in shell would be recognized as a variable, leading to a failure in subscription.

Publish

mqttx pub --help
OptionsDescription
-V, --mqtt-version <5/3.1.1/3.1>the MQTT version (default: 5)
-h, --hostname <HOST>the broker host (default: "localhost")
-p, --port <PORT>the broker port
-i, --client-id <ID>the client id
-q, --qos <0/1/2>the QoS of the message (default: 0)
-t, --topic <TOPIC>the message topic
-m, --message<MSG>the message body (default: "Hello From MQTTX CLI")
-r, --retainsend a retained message (default: false)
-s, --stdinread the message body from stdin
-M, --multilineread lines from stdin as multiple messages
-u, --username <USER>the username
-P, --password <PASS>the password
-f, --format <TYPE>the format type of the input message, support base64, json, hex and cbor
-l, --protocol <PROTO>the protocol to use, mqtt, mqtts, ws, or wss (default: mqtt)
--path <PATH>the path of websocket (default: /mqtt)
--key <PATH>path to the key file
--cert <PATH>path to the cert file
--capath to the ca certificate
--insecuredo not verify the server certificate
--alpn <PROTO...>set one or multiple ALPN (Application Layer Protocol Negotiation) protocols
-rp, --reconnect-period <MILLISECONDS>interval between two reconnections, disable auto reconnect by setting to 0 (default: 1000ms)
--maximum-reconnect-times <NUMBER>the maximum reconnect times (default: 10)
-up, --user-properties <USERPROPERTIES...>the user properties of MQTT 5.0 (e.g. -up "name: mqttx cli")
-pf, --payload-format-indicatorthe payload format indicator of the publish message
-e, --message-expiry-interval <NUMBER>the lifetime of the publish message in seconds
-ta, --topic-alias <NUMBER>value that is used to identify the topic instead of using the topic name
-rt, --response-topic <TOPIC>string which is used as the topic name for a response message
-cd, --correlation-data <DATA>used by the sender of the request message to identify which request the response message is for when it is received
-si, --subscription-identifier <NUMBER>the identifier of the subscription
-ct, --content-type <TYPE>a description of the content of the publish message
-Wt, --will-topic <TOPIC>the will topic
-Wm, --will-message <BODY>the will message
-Wq, --will-qos <0/1/2>the will qos
-Wr, --will-retainsend a will retained message (default: false)
-Wd, --will-delay-interval <SECONDS>the will delay interval in seconds
-Wpf, --will-payload-format-indicatorwill message is UTF-8 encoded character data or not
-We, --will-message-expiry-interval <SECONDS>lifetime of the will message in seconds
-Wct, --will-content-type <CONTENTTYPE>description of the will message’s content
-Wrt, --will-response-topic <TOPIC>topic name for a response message
-Wcd, --will-correlation-data <DATA>correlation data for the response message
-Wup, --will-user-properties <USERPROPERTIES...>the user properties of will message
-se, --session-expiry-interval <SECONDS>the session expiry interval in seconds
--rcv-max, --receive-maximum <NUMBER>the receive maximum value
--maximum-packet-size <NUMBER>the maximum packet size the client is willing to accept
--topic-alias-maximum <NUMBER>the topic alias maximum value
--req-response-infothe client requests response information from the server
--no-req-problem-infothe client requests problem information from the server
-Cup, --conn-user-properties <USERPROPERTIES...>the connect user properties of MQTT 5.0 (e.g. -Cup "name: mqttx cli")
--save [PATH]save the parameters to the local configuration file, which supports json and yaml format, default path is ./mqttx-cli-config.json
--config [PATH]load the parameters from the local configuration file, which supports json and yaml format, default path is ./mqttx-cli-config.json
--helpdisplay help for pub command
-Pp, --protobuf-path <PATH>the path to the .proto file that defines the message format for Protocol Buffers (protobuf)
-Pmn, --protobuf-message-name <NAME>the name of the protobuf message type (must exist in the .proto file)
--debugEnable debug mode for MQTT.js (default: false)

Benchmark

The bench command is used to test the performance of the broker. It has basically the same as the normal command options, the following will only list the new or changed options.

Connect Benchmark

mqttx bench conn --help
OptionsDescription
-c, --count <NUMBER>the number of connections (default: 1000)
-i, --interval <MILLISECONDS>interval of connecting to the broker (default: 10ms)
-I, --client-id <ID>the client id, support %i (index) variable

Subscribe Benchmark

mqttx bench sub --help
OptionsDescription
-c, --count <NUMBER>the number of connections (default: 1000)
-i, --interval <MILLISECONDS>interval of connecting to the broker (default: 10ms)
-I, --client-id <ID>the client id, support %i (index) variable
-t, --topic <TOPIC...>the message topic, support %u (username), %c (client id), %i (index) variables
-v, --verboseprint history received messages and rate

Publish Benchmark

mqttx bench pub --help
OptionsDescription
-c, --count <NUMBER>the number of connections (default: 1000)
-i, --interval <MILLISECONDS>interval of connecting to the broker (default: 10ms)
-im, --interval-message <MILLISECONDS>interval of publishing message to the broker (default: 1000ms)
-L, --limit <NUMBER>the number of messages to publish, 0 means unlimited (default: 0)
-I, --client-id <ID>the client id, support %i (index) variable
-t, --topic <TOPIC...>the message topic, support %u (username), %c (client id), %i (index) variables
-v, --verboseprint history received messages and rate
-s, --stdinread the message body from stdin
-M, --multilineread lines from stdin as multiple messages

Typical stress test scenario

Connection test

Create 10000 connections at a rate of one connection every 10ms, with client ID mqttx-bench-%i:

mqttx bench conn -c 10000 -i 10 -I "mqttx-bench-%i"

If you are using EMQX, you can check the number of connections in EMQX after all connections have been established via EMQX Dashboard or by running ./bin/emqx_ctl listeners to see the information about the number of connections in EMQX.

tcp:default
  listen_on       : :1883
  acceptors       : 16
  proxy_protocol  : false
  running         : true
  current_conn    : 10000
  max_conns       : 1024000

Throughput test

Start 500 clients, subscribe to topic mqttx/bench/t:

mqttx bench sub -c 500 -t mqttx/bench/t

Then start 20 publishers, publishing messages to the topic mqttx/bench/t at a rate of 10 messages per second with the message mqttx bench test:

mqttx bench pub -c 20 -im 100 -t mqttx/bench/t -m "mqttx bench test"

Then, go back to the subscribing client, you can see the total number of messages received and the real-time message rate:

Received total: 10989500, rate: 100000/s

Simulate

For simulating MQTT publish message in specific scenarios.

It has basically the same as the Publish Benchmark command options, the following will only list the new or changed options.

mqttx simulate --help
OptionsDescription
-sc, --scenario <SCENARIO>the name of the built-in scenario to simulate
-f, --file <SCENARIO FILE PATH>file path of a local custom scenario script
-t, --topic <TOPIC... >the message topic, optional, supports variables such as %u (username), %c (client id), %i (index), %sc (scenario). Default topic format is mqttx/simulate/%sc/%c

One of the --scenario and --file parameters must be specified, and if both are specified, the --file parameter is preferred.

Custom IoT Data Script

Example:

/**
 * MQTTX Scenario file example
 *
 * This script generates random temperature and humidity data.
 */
function generator(faker, options) {
  return {
    // If no topic is returned, use the topic in the command line parameters.
    // Topic format: 'mqttx/simulate/myScenario/' + clientId,
    message: JSON.stringify({
      temp: faker.datatype.number({ min: 20, max: 80 }), // Generate a random temperature between 20 and 80.
      hum: faker.datatype.number({ min: 40, max: 90 }), // Generate a random humidity between 40 and 90.
    })
  }
}
// Export the scenario module
module.exports = {
  name: 'myScenario', // Name of the scenario
  generator, // Generator function
}

For more examples and detailed editing guides, please refer to the scripts-example in the MQTTX GitHub repository, or see how to use faker.js to generate various types of random data.

Built-in Scenarios

MQTTX CLI has built-in some common scenarios, which can be specified by the --scenario parameter, for example:

mqttx simulate --scenario tesla

You can use the ls command to list all the built-in scenarios:

mqttx ls --scenarios

This command will output a table that shows the name and description of each built-in scenario. If you want to use one of them in the simulate command, simply specify the scenario name in the --scenario option:

mqttx simulate --scenario <SCENARIO_NAME>

List of built-in scenarios:

Scenario NameDescription
teslaSimulate Tesla vehicle data
IEMSimulation to generate Industrial Energy Monitoring data
smart_homeSimulation to generate Smart Home data
weatherSimulation to generate advanced weather station's data.

List

The list command provides an overview of available resources.

Currently, it supports listing built-in scenarios.

mqttx list --help
OptionsDescription
-sc, --scenarioslist the built-in scenarios

Configuration

MQTTX CLI supports the import and export of configurations, so that users can save command parameters to a local configuration file for future use.

The configuration file supports json and yaml formats, and the default path is ./mqttx-cli-config.json.

Here is an example of exporting and importing configurations for the conn command:

Export configuration

# Save to default path
mqttx conn --save

# Save to specified path
mqttx conn --save ../custom/mqttx-cli.json

# Save to specified path and specify the format as yaml
mqttx conn --save ../custom/mqttx-cli.yaml

Import configuration

# Import configuration from default path
mqttx conn --config

# Import configuration from specified path
mqttx conn --config ../custom/mqttx-cli.json

# Import configuration from specified path and specify the format as yaml
mqttx conn --config ../custom/mqttx-cli.yaml

Data Pipeline

MQTTX CLI provides a simple way to manage and pipeline MQTT data. Its clean mode and jq eliminate the need for complex coding to process MQTT data.

For example, to subscribe and extract an MQTT packet's payload or restructure data:

mqttx sub -t topic --output-mode clean | jq '.payload'

mqttx sub -t topic --output-mode clean | jq '{topic, payload, retain: .packet.retain, userProperties: .packet.properties.userProperties}'

This example shows how to leverage the functionality of MQTTX CLI, jq and other tools to quickly and efficiently build pipelines for acquiring and processing IoT data.