FAQ

Q: What is MQTTX CLI?

MQTTX CLI (mqttx) is a free, open-source (Apache-2.0) MQTT 5.0 command-line client by EMQ. It runs on Windows, macOS, and Linux and lets you connect to MQTT brokers, publish and subscribe to messages, run benchmarks, and simulate IoT data from the terminal, without a graphical interface.

Q: How do I install MQTTX CLI?

On macOS and Linux, run: curl -fsSL https://emqx.sh/mqttx | sh On Windows, run irm https://emqx.sh/mqttx.ps1 | iex in PowerShell. See Installation for Homebrew, NPM, Docker and other options.

Q: How do I test an MQTT broker from the command line?

Subscribe in one terminal and publish in another: mqttx sub -t 'hello' -h 'broker.emqx.io' -p 1883 mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 -m 'from MQTTX CLI' To only check that the broker accepts a connection, run mqttx conn -h 'broker.emqx.io' -p 1883.

Q: How do I connect over TLS or WebSocket?

Use -l, --protocol to choose mqtt, mqtts, ws, or wss. For TLS, pass --ca, and for mutual TLS also --cert and --key. Use --insecure only for testing, because it skips server certificate verification. For WebSocket, --path sets the path (default /mqtt) and -wh adds headers. See Connection for all options.

Q: Can MQTTX CLI benchmark an MQTT broker?

Yes. mqttx bench conn, mqttx bench sub, and mqttx bench pub measure connection, subscribe, and publish performance with many concurrent clients, for example mqttx bench pub -c 5000 -t bench/%i. See Benchmark.

Q: Can MQTTX CLI generate simulated IoT data?

Yes. mqttx simulate publishes data from built-in scenarios (list them with mqttx ls -sc) or from your own JavaScript scripts, for example mqttx simulate -sc tesla -c 10. See Simulate.

Q: How do I avoid retyping the same options?

Save options to a JSON or YAML file with -so, --save-options and load them later with -lo, --load-options. Run mqttx init to create a default configuration file. See Configuration File.

Q: How do I check for updates?

Run mqttx check to see whether a newer version of MQTTX CLI is available.

What is MQTTX CLI?

MQTTX CLI (mqttx) is a free, open-source (Apache-2.0) MQTT 5.0 command-line client by EMQ. It runs on Windows, macOS, and Linux and lets you connect to MQTT brokers, publish and subscribe to messages, run benchmarks, and simulate IoT data from the terminal, without a graphical interface.

How do I install MQTTX CLI?

On macOS and Linux, run:

curl -fsSL https://emqx.sh/mqttx | sh

On Windows, run irm https://emqx.sh/mqttx.ps1 | iex in PowerShell. See Installation for Homebrew, NPM, Docker and other options.

How do I test an MQTT broker from the command line?

Subscribe in one terminal and publish in another:

mqttx sub -t 'hello' -h 'broker.emqx.io' -p 1883
mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 -m 'from MQTTX CLI'

To only check that the broker accepts a connection, run mqttx conn -h 'broker.emqx.io' -p 1883.

How do I connect over TLS or WebSocket?

Use -l, --protocol to choose mqtt, mqtts, ws, or wss. For TLS, pass --ca, and for mutual TLS also --cert and --key. Use --insecure only for testing, because it skips server certificate verification. For WebSocket, --path sets the path (default /mqtt) and -wh adds headers. See Connection for all options.

Which MQTT versions does MQTTX CLI support?

MQTT 5.0, 3.1.1, and 3.1. MQTT 5.0 is the default; choose another version with -V, --mqtt-version. MQTT 5.0 features are available as options, such as user properties (-up), session expiry interval (-se), and retain handling on sub (-rh).

Can MQTTX CLI benchmark an MQTT broker?

Yes. mqttx bench conn, mqttx bench sub, and mqttx bench pub measure connection, subscribe, and publish performance with many concurrent clients, for example mqttx bench pub -c 5000 -t bench/%i. See Benchmark.

Can MQTTX CLI generate simulated IoT data?

Yes. mqttx simulate publishes data from built-in scenarios (list them with mqttx ls -sc) or from your own JavaScript scripts, for example mqttx simulate -sc tesla -c 10. See Simulate.

How do I avoid retyping the same options?

Save options to a JSON or YAML file with -so, --save-options and load them later with -lo, --load-options. Run mqttx init to create a default configuration file. See Configuration File.

Can AI coding agents use MQTTX CLI?

Yes. The mqttx-cli Agent Skill teaches AI coding agents such as Claude Code and Cursor to run MQTTX CLI correctly for connection checks, pub/sub round trips, benchmarks, and troubleshooting. Install it with npx skills add emqx/MQTTX --skill mqttx-cli.

How do I check for updates?

Run mqttx check to see whether a newer version of MQTTX CLI is available.