# MQTTX Command Line

Connects, publishes and subscribes to MQTT brokers with the mqttx command.

- Repository: https://github.com/emqx/MQTTX (5091 stars)
- Category: DevOps
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add emqx/MQTTX --skill mqttx-cli -g -a claude-code -y`
Codex: `npx skills add emqx/MQTTX --skill mqttx-cli -g -a codex -y`
Cursor: `npx skills add emqx/MQTTX --skill mqttx-cli -g -a cursor -y`
Gemini CLI: `npx skills add emqx/MQTTX --skill mqttx-cli -g -a gemini-cli -y`

## Description

Use MQTTX CLI for MQTT connections, publishing and subscriptions, MQTT 5 features, TLS and SCRAM authentication, payload codecs and schemas, benchmarks, built-in or custom data simulation, configuration, installation and troubleshooting. Use when operating or testing MQTT through the mqttx command. Does not operate MQTTX Desktop or administer a broker.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# MQTTX CLI

## Prepare

1. Locate `mqttx`, read `mqttx --version`, then inspect `mqttx <command> --help` for the task. Treat installed help as authoritative; release channels can differ. If missing or a required feature is unavailable, follow the repository's root `INSTALL.md`, or its [standalone installation guide](https://github.com/emqx/MQTTX/blob/main/INSTALL.md) when this skill has been copied elsewhere. Do not update a working CLI on every invocation.
2. Establish the broker hostname, port, transport (`mqtt`, `mqtts`, `ws`, `wss`), MQTT version, credentials, topic and intended operation from the user's context. Ask only for missing information that affects execution. Use the requested broker; do not substitute a public broker after a failure.
3. Account for `~/.mqttx-cli/config`, which can supply default host, port, protocol and credentials. Do not print its secrets or overwrite it for a one-off task. Explicit CLI arguments override defaults; `--load-options` loads command-specific JSON/YAML options, with explicitly supplied CLI arguments taking precedence. See [configuration and utility commands](references/configuration.md) for initialization, saving and loading.
4. Set a finite observation deadline for connection/subscription tasks and retain a handle to each process started. Use the agent's process controller or an available OS timeout tool; a tool returning a session handle is not necessarily a deadline. Terminate and wait for owned processes at completion or timeout.

The CLI command registration in this repository (1.13.0) does not offer general `--timeout`, `--max-messages`, `--json` or `--output jsonl` flags. Do not invent them. Recheck help for other versions. `--reconnect-period 0` disables reconnection; it is not an overall deadline. `conn` stays connected after success and `sub` keeps listening until stopped.

## Choose a workflow

The rest: https://github.com/emqx/MQTTX/blob/HEAD/skills/mqttx-cli/SKILL.md