Command-line reference
mqtt_client_sample [options]
Note
This is not a comprehensive option list. Run mqtt_client_sample --help to view all options.Connection options
| Flag | Description | Default |
|---|
--mqtt_servername <host> | Broker host name or IP. | — |
--mqtt_port <port> | Broker port. | 1883 |
| `–mqtt_version <5 | 3.1.1>` | Protocol version. |
--mqtt_client_id <id> | Client identifier (generated UUID if omitted). | — |
--mqtt_keep_alive <sec> | Keep‑alive interval. | 0 (disabled) |
| `–mqtt_transport <TCP | SSL>` | Select TCP or TLS. |
--proxy <url> | HTTP/HTTPS forward proxy. | — |
--print_hex_bytes | Display payload bytes in hexadecimal. | Off |
--help | Show built‑in help. | — |
Session control
| Flag | Purpose |
|---|
--mqtt_clean_start | Start a new session. |
--mqtt_session_expiry_interval <sec> | Persist the session after disconnect (0, 1 – 4294967294, 4294967295). |
Subscribe / unsubscribe
| Flag | Description |
|---|
--mqtt_sub_topic <topic> | Add a subscription (repeatable). |
--mqtt_sub_topic_single | Send one SUBSCRIBE per filter. |
--mqtt_sub_topic_no_local_option | Ignore messages published by this client (MQTT 5). |
--mqtt_sub_topic_retain_as_published | Preserve retain flag on incoming messages (MQTT 5). |
| `–mqtt_sub_topic_retain_handling <0 | 1 |
--mqtt_unsub_topic <topic> | Remove a subscription (repeatable). |
--mqtt_unsub_topic_single | Send one UNSUBSCRIBE per filter. |
Publish
| Flag | Description | Default |
|---|
--mqtt_pub_topic <topic> | Topic for the next message (repeatable). | — |
--mqtt_pub_message <text> | Payload text for the most‑recent topic. | — |
--mqtt_pub_file <path> | Payload file for the most‑recent topic. | — |
| `–mqtt_pub_qos <0 | 1 | 2>` |
--mqtt_pub_retain | Set the retain flag. | Off |
Last‑will message
| Flag | Description |
|---|
--mqtt_will_topic <topic> | Will topic. |
--mqtt_will_message <text> | Will payload. |
| `–mqtt_will_qos <0 | 1 |
--mqtt_will_retain | Retain the will message. |
Property flags (MQTT 5)
| Packet | Flag prefix |
|---|
| CONNECT | --mqtt_connect_properties |
| PUBLISH | --mqtt_publish_properties |
| SUBSCRIBE | --mqtt_subscribe_properties |
| UNSUBSCRIBE | --mqtt_unsubscribe_properties |
| DISCONNECT | --mqtt_disconnect_properties |
| WILL | --mqtt_will_properties |
Example
--mqtt_connect_properties receive_maximum 32
--mqtt_publish_properties topic_alias 3
TLS options
| Flag | Description |
|---|
--ssl_ca_file <file> | CA bundle for server verification. |
--ssl_allow_untrusted | Skip certificate verification (test only). |
--ssl_cert_file <file> | Client certificate (mutual TLS). |
--ssl_key_file <file> | Private key for --ssl_cert_file. |
Example commands
Minimal publish (plain TCP)
mqtt_client_sample \
--mqtt_servername broker.hivemq.com \
--mqtt_port 1883 \
--mqtt_pub_topic sensors/temp \
--mqtt_pub_message 22.5 \
--mqtt_clean_start
TLS subscribe with advanced options
mqtt_client_sample \
--mqtt_servername broker.hivemq.com \
--mqtt_port 8883 \
--mqtt_transport SSL \
--ssl_ca_file /etc/ssl/certs/ca-bundle.crt \
--mqtt_sub_topic alerts/# \
--mqtt_sub_topic_no_local_option \
--mqtt_sub_topic_retain_handling 1 \
--mqtt_clean_start