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
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/%i
Version Check
mqttx check
Use
mqttx --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 |
Connection
mqttx conn --help
| Options | Description |
|---|---|
| -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-clean | set 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 or mqtts (default: mqtt) |
| --key <PATH> | path to the key file |
| --cert <PATH> | path to the cert file |
| --ca <PATH> | path to the ca certificate |
| --insecure | do not verify the server certificate |
| -rp, --reconnect-period <MILLISECONDS> | interval between two reconnections, disable auto reconnect by setting to 0 (default: 1000ms) |
| --maximun-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-retain | send a will retained message (default: false) |
| -Wd, --will-delay-interval <SECONDS> | 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 <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-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 |
Publish
mqttx sub --help
| Options | Description |
|---|---|
| -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-clean | set 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 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> | path to the key file |
| --cert <PATH> | path to the cert file |
| --ca | path to the ca certificate |
| --insecure | do not verify the server certificate |
| -rp, --reconnect-period <MILLISECONDS> | interval between two reconnections, disable auto reconnect by setting to 0 (default: 1000ms) |
| --maximun-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 |
| -v, --verbose | print the topic before the 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-retain | send a will retained message (default: false) |
| -Wd, --will-delay-interval <SECONDS> | 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 <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-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 |
Subscribe
mqttx pub --help
| Options | Description |
|---|---|
| -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 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 <USER> | the username |
| -P, --password <PASS> | the password |
| -l, --protocol <PROTO> | the protocol to use, mqtt or mqtts (default: mqtt) |
| --key <PATH> | path to the key file |
| --cert <PATH> | path to the cert file |
| --ca | path to the ca certificate |
| --insecure | do not verify the server certificate |
| -rp, --reconnect-period <MILLISECONDS> | interval between two reconnections, disable auto reconnect by setting to 0 (default: 1000ms) |
| --maximun-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-indicator | the 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-retain | send a will retained message (default: false) |
| -Wd, --will-delay-interval <SECONDS> | 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 <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-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 |
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
| Options | Description |
|---|---|
| -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
| Options | Description |
|---|---|
| -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, --verbose | print history received messages and rate |
Publish Benchmark
mqttx bench pub --help
| Options | Description |
|---|---|
| -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) |
| -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, --verbose | print history received messages and rate |
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
Configuration
MQTT X 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