Installation

MQTTX CLI runs on Windows, macOS, and Linux. Install it with one of:

Install Script

Installs the right build for your OS and CPU into your home directory. No sudo needed.

macOS and Linux:

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

Windows (PowerShell):

irm https://emqx.sh/mqttx.ps1 | iex

Run it again to update. On Alpine Linux, install curl first (apk add curl).

mqttx goes to ~/.local/bin on macOS and Linux, or %LOCALAPPDATA%\Programs\mqttx-cli\bin on Windows (added to PATH). If the command is not found, the script prints the PATH line to add.

Options

Variable	Description
`MQTTX_VERSION`	Version to install, e.g. `1.13.0`. Default: latest
`MQTTX_INSTALL_DIR`, `MQTTX_BIN_DIR`	Where the binary and the `mqttx` command go

curl -fsSL https://emqx.sh/mqttx | MQTTX_VERSION=1.13.0 sh

Uninstall

On macOS and Linux, remove the command and the installed files:

rm ~/.local/bin/mqttx
rm -rf ~/.local/share/mqttx-cli

On Windows, delete %LOCALAPPDATA%\Programs\mqttx-cli and remove its bin folder from your user PATH in Settings > Environment Variables.

Homebrew

On macOS, install with Homebrew:

brew install emqx/mqttx/mqttx-cli

NPM

Requires Node.js.

npm install mqttx-cli -g

Docker

First, pull the image:

docker pull emqx/mqttx-cli

Interactive Mode

To start an interactive shell session within the container (allowing multiple commands):

docker run -it --rm emqx/mqttx-cli

Once inside the container's shell, you can run mqttx commands (e.g., mqttx conn, mqttx pub). For example:

❯ docker run -it --rm emqx/mqttx-cli
/app # mqttx conn -h broker.emqx.io -p 1883
✔ Connected
- Press Ctrl+C to disconnect and exit

One-off Command Execution

To execute a single MQTTX command directly without entering the shell:

# Example: Connect to a broker
docker run --rm emqx/mqttx-cli mqttx conn -h broker.emqx.io -p 1883

# Example: Publish a message
docker run --rm emqx/mqttx-cli mqttx pub -t test -m "hello world" -h broker.emqx.io

# Example: Subscribe to a topic
docker run --rm emqx/mqttx-cli mqttx sub -t test -h broker.emqx.io

Manual Download

Download packaged binaries from the MQTTX CLI download page, the releases page, or More Downloads. Choose the asset that matches your platform and CPU architecture:

Platform	Asset
macOS Intel	`mqttx-cli-macos-x64`
macOS Apple Silicon	`mqttx-cli-macos-arm64`
Linux x86-64	`mqttx-cli-linux-x64`
Linux ARM64	`mqttx-cli-linux-arm64`
Alpine x86-64	`mqttx-cli-alpine-x64`
Alpine ARM64	`mqttx-cli-alpine-arm64`
Windows x64	`mqttx-cli-win-x64.exe`
Windows ARM64	`mqttx-cli-win-arm64.exe`

The example below downloads the latest published release on macOS or Linux and installs it for your user without sudo:

curl -fLo mqttx https://github.com/emqx/MQTTX/releases/latest/download/mqttx-cli-linux-x64
chmod +x mqttx
mkdir -p ~/.local/bin && mv mqttx ~/.local/bin/mqttx

Replace mqttx-cli-linux-x64 with the asset name for your platform. For a system-wide install, run sudo install -m 755 mqttx /usr/local/bin/mqttx instead of moving the file into ~/.local/bin.

To install a specific version, select its assets on the releases page.

On Windows, download the .exe asset for your architecture and run it from a terminal.

Note: When using commands that require input string data, please be aware to use double quotes in Windows cmd, while single quotes can be used in PowerShell. Additionally, the paths use \ while in other operating systems they use /.

Verify Installation

After installation, you can verify that the installation is successful by running the following command:

mqttx -v