---
title: "Command-line reference"
source_url: https://dev.digicert.com/trustcore-sdk/nanomqtt/command-line-reference.html
---

```
mqtt_client_sample [options]
```


> **Info**
>
> 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. | 5 |
| `--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. | TCP |
| `--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|2>` | Control retained message delivery (MQTT 5). |
| `--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>` | QoS for the most‑recent message. | 0 |
| `--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|2>` | Will QoS. |
| `--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**

```bash
--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)**

```bash
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**

```bash
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
```