MQTTX CLI 能力全景速查：1.13.0 全部命令、注册旗标与版本特例实战指南

• 开发工具
• 物联网
• 后端

MQTTX CLI 是 EMQ 开源的跨平台 MQTT 命令行客户端，本指南基于仓库中skills/mqttx-cli/references/capabilities.md这份「能力地图」文档，结合 cli/src/index.ts 的命令注册源码，为读者完整呈现MQTTX CLI 1.13.0中所有可执行命令、全部已注册旗标（flag）及其适用命令范围、以及版本特有缺陷与维护验证基线。读完本文，你将能精确判断任一参数在哪条命令上可用、哪些组合在协议层面不合法、哪些已知边界需要绕开，从而在实际连接、发布订阅、性能测试与数据仿真任务中不再依赖猜测。

能力地图的定位与成文基线

capabilities.md是一张面向开发者和 AI Agent 的「能力覆盖地图」（capability map），它的校验基线非常明确：

• 覆盖基线：仓库cli/src/index.ts中的命令注册与其各处理器（handlers），对应版本1.13.0。
• 校验方式：所有已注册的可执行命令都被统一路由到本文的表单中；旗标表格与命令注册逐项比对。
• 权威来源：文档明确提示「以安装后实际输出的--help为准」，因为发布渠道可能存在差异；表格记录的是「可用性」，并不承诺每个组合都合法或没有 bug。

从源码看，命令注册集中在 cli/src/index.ts 的Commander类中（index.ts），基于commander库构建，根命令名为mqttx，描述为 "An MQTT client for the command line"（index.ts）。所有命令都设置了.allowUnknownOption(false)，即遇到未注册参数会直接报错退出——这正是能力地图能做到「逐项比对」的前提。

命令全景：八大命令家族

capabilities.md 将全部已注册命令归为以下几组：

对照源码注册位置，可以确认这张表与实际实现一一对应：

• conn：创建连接并连接到 MQTT Broker，注册于 index.ts，处理器为conn（定义于 cli/src/lib/conn.ts）。注意conn成功后会保持连接，直到被外部终止。
• pub：向主题发布一条消息，注册于 index.ts，处理器为pub（cli/src/lib/pub.ts）。
• sub：订阅一个或多个主题，注册于 index.ts，处理器为sub（cli/src/lib/sub.ts）。sub会持续监听直到被停止。
• bench conn / bench pub / bench sub：性能测试三件套，注册于 index.ts。其中bench pub的处理器为benchPub，bench sub为benchSub，bench conn为benchConn。
• simulate：按内置或自定义场景发布仿真消息，注册于 index.ts，处理器为simulatePub，默认主题模板为mqttx/simulate/%sc/%c（index.ts）。
• ls：按选项列出信息，注册于 index.ts。ls --scenarios会扫描 cli/src/scenarios 目录下的所有.js场景文件并以表格输出名称与描述（实现见 cli/src/lib/ls.ts）。
• init：交互式初始化配置文件（index.ts），处理器initConfig位于 cli/src/lib/init.ts。
• check：检查更新（index.ts），处理器为checkUpdate（cli/src/utils/checkUpdate.ts），仅上报可用更新，不执行安装。

注册旗标总表：所有已注册选项一览

capabilities.md 引入了一个关键概念：Network指全部七个联网命令——conn、pub、sub、bench conn、bench pub、bench sub、simulate。凡标注为 Network 的旗标在这七个命令上都可用；标注了具体命令集合的旗标（如--keepalive仅限conn、pub、bench conn、bench pub、simulate）则不能想当然地用于其他命令。

下表完整继承原文档的全部 79 项注册旗标，右侧为适用命令与对应指南：

能力地图特别提醒：某旗标缺席于某条命令的行，就不能假定它在那个命令上可用。例如--keepalive不出现在sub行，意味着 1.13.0 的sub与bench sub不暴露该参数（详见 connections.md 的说明）；--debug只出现在conn、pub、sub三行，基准与仿真命令不接受它。

旗标背后的解析器实现

这张总表不是纸面文档，它直接对应 cli/src/utils/parse.ts 中一系列严格的参数解析器。理解这些解析器，就能解释表格中许多「看起来可用但实际受限」的细节：

• parseNumber（parse.ts）：任何非数字输入都会立即打印失败信息并process.exit(1)。因此--subscription-identifier这类看似「可变参数」的旗标实际走的是标量数值解析——能力地图中关于sub --subscription-identifier的特例正是由此而来。
• parseProtocol（parse.ts）：仅接受mqtt、mqtts、ws、wss四种取值，与表格中--protocol的取值域一致。
• parseMQTTVersion（parse.ts）：内部将3.1、3.1.1、5.0/5映射为数字3、4、5。这一映射同时决定了 options 文件中mqttVersion字段必须写成数字（详见 configuration.md）。
• parseKeyValues（parse.ts）：用户属性类参数（--user-properties、--will-user-properties、--ws-headers等）严格按key: value分隔符切分，重复键自动聚合成数组——这也解释了为什么「值本身包含:时需要改用 options 文件对象」。
• parseQoS（parse.ts）：校验范围 0–2，且会累积成数组，支持sub/bench sub的主题对齐 QoS。
• parseVariadicOfBooleanType（parse.ts）：只接受字面量true/false，对应--no_local、--retain-as-published的显式布尔值要求。
• parsePubTopic（parse.ts）：发布主题含+、#通配符会被直接拒绝并退出。
• parseFileRead（parse.ts）：文件读取受 cli/src/utils/constants.ts 中MQTT_SINGLE_MESSAGE_BYTE_LIMIT = 256MB的硬限制约束。
• parseFormat（parse.ts）：仅接受base64、json、hex、cbor、binary、msgpack，与 payloads.md 的六种格式一一对应。
• parseOutputMode（parse.ts）：仅clean与default两种。
• parseAuthenticationMethod（parse.ts）：SCRAM 认证方法只接受SCRAM-SHA-1、SCRAM-SHA-256、SCRAM-SHA-512。

连接选项的组装逻辑集中在parseConnectOptions（parse.ts）：TLS 证书通过fs.readFileSync读入（--key/--cert/--ca），--insecure映射为rejectUnauthorized: false，--alpn映射为ALPNProtocols，--ws-headers仅在ws/wss下允许（否则报错退出，见parseWsHeaders，parse.ts）。值得注意的源码细节：当--no-clean（clean: false）且未显式给出--session-expiry-interval时，MQTT 5 的会话过期时间会被强制设为0xFFFFFFFF（parse.ts），这与 mqtt-features.md 中「--no-clean默认会话过期0xFFFFFFFF」的说明完全吻合。

版本特例与已知边界

能力地图的核心价值之一，是它如实记录了 1.13.0 实现中的六条版本特例（version-specific checks），这些在纯--help输出中看不出来，但会在实际运行中踩坑：

1. simulate --maximun-reconnect-times拼写错误：旗标拼写与运行时读取的属性不一致。源码中simulate注册的确实是拼错的--maximun-reconnect-times（index.ts），而其它命令使用正确的--maximum-reconnect-times。文档明确建议不要依赖该旗标控制有限运行，改用外部截止时间（deadline）。
2. sub --subscription-identifier使用标量数值解析器：尽管--help宣称它是可变参数，当前实现的parseNumber不会按主题累积多个标识符。可行的替代是每次调用传一个标量，或通过带类型的 options 文件数组表达按主题的值。
3. 发布命令上注册了--subscription-identifier但协议不允许：MQTT 5 规范禁止客户端发起的 PUBLISH 包携带订阅标识符属性。源码中pub、bench pub、simulate确实注册了该旗标（如 index.ts），但这是「可用性」不等于「协议合法」的典型例子——broker 甚至可能因此断开客户端。切勿将其用于合法发布。
4. clean 输出绕过 schema 解码、并抑制就绪/部分错误日志：--output-mode clean会再次格式化原始载荷而不是 schema 解码后的值，同时隐藏连接/订阅就绪状态和部分错误；某些连接失败路径甚至返回退出码 0。因此「退出码 0 + clean 空输出」不能证明成功。
5. 管道多行输入绕过格式/schema 转换且有时序限制：-s -M（stdin + multiline）在管道模式下逐行发送已缓冲内容，不经过 format/schema 转换；--file-write追加文件时会把字节转为文本，不是无损二进制拼接。
6. 发布者/仿真器的%c主题展开与基准订阅不同：bench pub/simulate用基础 client-ID 模板替换%c，而bench sub用最终生成的每客户端 ID；bench sub的「全部订阅完成」就绪提示可能在部分订阅被拒绝时仍出现。

这些特例的共同处理原则是：不要通过修改 CLI 代码来绕开限制，而是选用文档给出的替代工作流；如果无法可靠表达所需行为，如实说明限制并采用最接近的受支持方案。

维护与验证基线

能力地图同时是一份维护文档，记录了更新技能时的规范动作与本次修订的实测基线：

更新流程：为新的发布版本更新本技能时，需要①将命令注册与安装后的--help与本文表格比对；②在改动示例前检查受影响的处理器实现；③重新核对上述特例而非原样沿用为通用规则；④在本机 broker 上用明确的边界和「非业务主题」实际验证命令组合，并记录哪些组合真正被验证过。文档特别强调「文档覆盖」与「实测互操作覆盖」是两件独立的事。

本次修订的验证基线：官方 Linux x64 CLI 1.13.0 + 隔离的 Mosquitto 2.0.22 监听器。实测覆盖了 MQTT 3.1/3.1.1/5.0、TLS 与 mTLS、WebSocket 请求头、通过 options 文件的密码认证、全部六种格式、Protobuf/Avro、随机载荷、stdin 与文件输入、管道/TTY 行模式、编号文件保存与追加分隔符、MQTT 5 发布/订阅属性、清除保留消息、持久会话投递、延迟遗嘱、全部三个基准命令、文件拆分、四个内置场景、自定义生成器、YAML 保存/加载以及check。第一阶段检查还验证了截止时间、clean 流解析与清理。

未被本次实测覆盖：针对增强认证 broker 的 SCRAM、服务特定的 ALPN、WSS、交互式init补全、macOS/Windows 执行，这些仅通过源码/帮助核对了旗标可用性，未做活体验证。文档要求：在目标环境中自行确认，不得仅凭语法检查就宣称互操作成功。另外，会话/遗嘱验证使用的是单独的匿名单监听器 broker（因为组合的认证监听器 fixture 未能投递那些消息）——broker 配置属于证据的一部分，而非 CLI 缺陷诊断。

结合实战：如何快速核对与落地

能力地图的日常用法是「先查表、再翻专项指南」。例如：

• 想用 WebSocket 连接：查表确认--protocol、--path为 Network 旗标，然后按 connections.md 的示例执行mqttx conn -h localhost -p 8083 -l ws --path /mqtt -V 5.0 --reconnect-period 0；--ws-headers解析要求key: value且冒号后带空格，值含分隔符时改用 options 文件。
• 想验证一次发布/订阅往返：按 workflows.md 的六步流程，先启动带截止时间的sub并等待Subscribed to ...就绪确认，再发布唯一标记消息，最后匹配精确主题与标记。
• 想做压力测试：查表确认--count、--interval、--limit等基准旗标，并按 benchmarks-and-simulation.md 明确设置连接数、速率、消息上限与运行时长——默认值是1000 连接 + 无限发布，必须显式给出边界。
• 想保存/复放参数：--save-options/--load-options支持 JSON/YAML（省略路径时默认./mqttx-cli-options.json），注意--save-options不是「仅保存」的干运行，保存后仍会执行网络操作（configuration.md）。
• 想了解某个旗标的精确取值范围与默认值：最权威的来源永远是安装后运行mqttx <command> --help，因为发布渠道可能携带不同实现；仓库根目录的 INSTALL.md 提供了安装/更新路径。

小结

capabilities.md这份能力地图回答了 MQTTX CLI 使用中最容易被忽略的问题：「这个参数到底在哪个命令上可用、为什么不可用、以及可用是否等于合法」。本文完整继承了其中的命令表、79 项注册旗标表、六条版本特例与维护验证基线，并用 cli/src/index.ts、cli/src/utils/parse.ts、cli/src/utils/constants.ts 等源码佐证了表格背后的实现逻辑。实践中请始终遵循两条铁律：以安装版本的--help为最终权威；对连接、订阅、基准等任何长驻或高负载命令一律施加外部截止时间与进程清理，再结合 连接与认证、MQTT 特性、载荷与文件、基准与仿真、配置与工具 及 故障排查 等专项指南安全落地。

• 开发工具
• 物联网
• 后端