English | 简体中文
MQTT X CLI is an open source MQTT 5.0 CLI Client and MQTT X on the command line. Designed to help develop and debug MQTT services and applications faster without the need to use a graphical interface.
MQTT stands for MQ Telemetry Transport. It is a publish/subscribe, extremely simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency or unreliable networks.
For introduction, installation, and usage, see the MQTT X CLI documentation. Below is a quick start guide.
To install the latest MQTTX CLI stable release on macOS using binary download.
Note: Please note CPU architecture of the current system environment
curl -LO https://www.emqx.com/en/downloads/MQTTX/v1.9.1/mqttx-cli-macos-x64
sudo install ./mqttx-cli-macos-x64 /usr/local/bin/mqttxcurl -LO https://www.emqx.com/en/downloads/MQTTX/v1.9.1/mqttx-cli-macos-arm64
sudo install ./mqttx-cli-macos-arm64 /usr/local/bin/mqttxbrew install emqx/mqttx/mqttx-cliTo install the latest MQTTX CLI stable release on Linux using binary download.
Note: Please note CPU architecture of the current system environment
curl -LO https://www.emqx.com/en/downloads/MQTTX/v1.9.1/mqttx-cli-linux-x64
sudo install ./mqttx-cli-linux-x64 /usr/local/bin/mqttxcurl -LO https://www.emqx.com/en/downloads/MQTTX/v1.9.1/mqttx-cli-linux-arm64
sudo install ./mqttx-cli-linux-arm64 /usr/local/bin/mqttxWindows users should go to the MQTT X release page and find the exe package for the corresponding system architecture, download it manually and execute.
npm install mqttx-cli -gdocker pull emqx/mqttx-cli
docker run -it --rm emqx/mqttx-cliDownload packaged binaries from the MQTT X releases page.
After installing it, run mqttx on the terminal
Connect
mqttx conn -h 'broker.emqx.io' -p 1883 -u 'admin' -P 'public'Subscribe
mqttx sub -t 'hello' -h 'broker.emqx.io' -p 1883Publish
mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 -m 'from MQTTX CLI'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/%imqttx --help| Options | Description |
|---|---|
| -v, --version | Output the version number |
| -h, --help | Display help for command |
| Command | Description |
|---|---|
| check | Check for updates |
| conn | Create a connection and connect to MQTT Broker |
| pub | Publish a message to a topic |
| sub | Subscribes to one or multiple topics |
| bench | MQTT Benchmark in performance testing |
mqttx conn --help| Options | Description |
|---|---|
| -V, --mqtt-version <5/3.1.1/3.1> | the MQTT version (default: 5) |
| -h, --hostname | the broker host (default: "localhost") |
| -p, --port | the broker port |
| -i, --client-id | the client id |
| --no-clean | set the clean session flag to false (default: true) |
| -k, --keepalive | send a ping every SEC seconds (default: 30) |
| -u, --username | the username |
| -P, --password | the password |
| -l, --protocol | the protocol to use, mqtt or mqtts (default: mqtt) |
| --key | path to the key file |
| --cert | path to the cert file |
| --ca | path to the ca certificate |
| --insecure | do not verify the server certificate |
| -rp, --reconnect-period | interval between two reconnections, disable auto reconnect by setting to 0 (default: 1000ms) |
| --maximun-reconnect-times | 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 | the will topic |
| -Wm, --will-message | the will message |
| -Wq, --will-qos <0/1/2> | the will qos |
| -Wr, --will-retain | send a will retained message (default: false) |
| -Wd, --will-delay-interval | the will delay interval in seconds |
| -Wpf, --will-payload-format-indicator | will message is UTF-8 encoded character data or not |
| -We, --will-message-expiry-interval | lifetime of the will message in seconds |
| -Wct, --will-content-type | description of the will message’s content |
| -Wrt, --will-response-topic | topic name for a response message |
| -Wcd, --will-correlation-data | correlation data for the response message |
| -Wup, --will-user-properties <USERPROPERTIES...> | the user properties of will message |
| -se, --session-expiry-interval | the session expiry interval in seconds |
| --rcv-max, --receive-maximum | the receive maximum value |
| --maximum-packet-size | the maximum packet size the client is willing to accept |
| --topic-alias-maximum | the topic alias maximum value |
| --req-response-info | the client requests response information from the server |
| --no-req-problem-info | the 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 |
| --help | display help for conn command |
mqttx sub --help| Options | Description |
|---|---|
| -V, --mqtt-version <5/3.1.1/3.1> | the MQTT version (default: 5) |
| -h, --hostname | the broker host (default: "localhost") |
| -p, --port | the broker port |
| -i, --client-id | the client id |
| -q, --qos <0/1/2> | the QoS of the message (default: 0) |
| --no-clean | set the clean session flag to false (default: true) |
| -t, --topic | the message topic |
| -k, --keepalive | send a ping every SEC seconds (default: 30) |
| -u, --username | the username |
| -P, --password | the password |
| -l, --protocol | the protocol to use, mqtt or mqtts (default: mqtt) |
| -nl, --no_local | the no local MQTT 5.0 flag |
| -rap, --retain-as-published | the retain as published MQTT 5.0 flag |
| -rh, --retain-handling <0/1/2> | the retain handling MQTT 5.0 |
| --key | path to the key file |
| --cert | path to the cert file |
| --ca | path to the ca certificate |
| --insecure | do not verify the server certificate |
| -rp, --reconnect-period | interval between two reconnections, disable auto reconnect by setting to 0 (default: 1000ms) |
| --maximun-reconnect-times | 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 | format the message body, support base64, json, hex |
| -v, --verbose | print 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 | the will topic |
| -Wm, --will-message | the will message |
| -Wq, --will-qos <0/1/2> | the will qos |
| -Wr, --will-retain | send a will retained message (default: false) |
| -Wd, --will-delay-interval | the will delay interval in seconds |
| -Wpf, --will-payload-format-indicator | will message is UTF-8 encoded character data or not |
| -We, --will-message-expiry-interval | lifetime of the will message in seconds |
| -Wct, --will-content-type | description of the will message’s content |
| -Wrt, --will-response-topic | topic name for a response message |
| -Wcd, --will-correlation-data | correlation data for the response message |
| -Wup, --will-user-properties <USERPROPERTIES...> | the user properties of will message |
| -se, --session-expiry-interval | the session expiry interval in seconds |
| -si, --subscription-identifier | the identifier of the subscription |
| --rcv-max, --receive-maximum | the receive maximum value |
| --maximum-packet-size | the maximum packet size the client is willing to accept |
| --topic-alias-maximum | the topic alias maximum value |
| --req-response-info | the client requests response information from the server |
| --no-req-problem-info | the 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 |
| --help | display help for sub command |
mqttx pub --help| Options | Description |
|---|---|
| -V, --mqtt-version <5/3.1.1/3.1> | the MQTT version (default: 5) |
| -h, --hostname | the broker host (default: "localhost") |
| -p, --port | the broker port |
| -i, --client-id | the client id |
| -q, --qos <0/1/2> | the QoS of the message (default: 0) |
| --no-clean | set the clean session flag to false (default: true) |
| -t, --topic | the message topic |
| -m, --message | the message body (default: "Hello From MQTT X CLI") |
| -r, --retain | send a retained message (default: false) |
| -s, --stdin | read the message body from stdin |
| -M, --multiline | read lines from stdin as multiple messages |
| -u, --username | the username |
| -P, --password | the password |
| -l, --protocol | the protocol to use, mqtt or mqtts (default: mqtt) |
| --key | path to the key file |
| --cert | path to the cert file |
| --ca | path to the ca certificate |
| --insecure | do not verify the server certificate |
| -rp, --reconnect-period | interval between two reconnections, disable auto reconnect by setting to 0 (default: 1000ms) |
| --maximun-reconnect-times | 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-indicator | the payload format indicator of the publish message |
| -e, --message-expiry-interval | the lifetime of the publish message in seconds |
| -ta, --topic-alias | value that is used to identify the topic instead of using the topic name |
| -rt, --response-topic | string which is used as the topic name for a response message |
| -cd, --correlation-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 | the identifier of the subscription |
| -ct, --content-type | a description of the content of the publish message |
| -Wt, --will-topic | the will topic |
| -Wm, --will-message | the will message |
| -Wq, --will-qos <0/1/2> | the will qos |
| -Wr, --will-retain | send a will retained message (default: false) |
| -Wd, --will-delay-interval | the will delay interval in seconds |
| -Wpf, --will-payload-format-indicator | will message is UTF-8 encoded character data or not |
| -We, --will-message-expiry-interval | lifetime of the will message in seconds |
| -Wct, --will-content-type | description of the will message’s content |
| -Wrt, --will-response-topic | topic name for a response message |
| -Wcd, --will-correlation-data | correlation data for the response message |
| -Wup, --will-user-properties <USERPROPERTIES...> | the user properties of will message |
| -se, --session-expiry-interval | the session expiry interval in seconds |
| --rcv-max, --receive-maximum | the receive maximum value |
| --maximum-packet-size | the maximum packet size the client is willing to accept |
| --topic-alias-maximum | the topic alias maximum value |
| --req-response-info | the client requests response information from the server |
| --no-req-problem-info | the 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 |
| --help | display help for pub command |
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.
mqttx bench conn --help| Options | Description |
|---|---|
| -c, --count | the number of connections (default: 1000) |
| -i, --interval | interval of connecting to the broker (default: 10ms) |
| -I, --client-id | the client id, support %i (index) variable |
mqttx bench sub --help| Options | Description |
|---|---|
| -c, --count | the number of connections (default: 1000) |
| -i, --interval | interval of connecting to the broker (default: 10ms) |
| -I, --client-id | the client id, support %i (index) variable |
| -t, --topic <TOPIC...> | the message topic, support %u (username), %c (client id), %i (index) variables |
| -v, --verbose | print history received messages and rate |
mqttx bench pub --help| Options | Description |
|---|---|
| -c, --count | the number of connections (default: 1000) |
| -i, --interval | interval of connecting to the broker (default: 10ms) |
| -im, --interval-message | interval of publishing message to the broker (default: 1000ms) |
| -I, --client-id | the client id, support %i (index) variable |
| -t, --topic <TOPIC...> | the message topic, support %u (username), %c (client id), %i (index) variables |
| -v, --verbose | print history received messages and rate |
MQTT X is designed to connect to test MQTT Brokers such as EMQX, The one-click connection and simple graphical interface make it easy to connect to EMQX or EMQX Cloud to debug and explore functional features.
Sign up EMQX Cloud for 14 days free trial
Download EMQX locally right now
- Follow @EMQTech on Twitter.
- If you have a specific question, check out our discussion forums.
- For general discussions, join us on the official Discord team.
- Keep updated on EMQX YouTube by subscribing.
Recommended version for Node environment:
- v16.*.*
# Clone
git clone [email protected]:emqx/MQTTX.git
# Install dependencies
cd MQTTX/cli
yarn install
# Compiles and hot-reloads for development
yarn run dev
# Compiles and minifies for production
yarn run buildAfter a successful build, the corresponding file for the successful build will appear in the dist directory and will need to be used in a Node.js environment.
If you need to package a binary executable, please refer to the following command.
# Install pkg lib
npm install pkg -g
# Build binary
pkg package.jsonAfter a successful build, you will see the binary executable for each system in the release directory.
Please make sure to read the Contributing Guide before making a pull request.
Apache License 2.0, see LICENSE.