Subscribe
Subscribes a client to one or more topics. If the Subscribe command is not called in Shell-Mode, it will block the console and write the received publishes to the console.
$ mqtt subscribe
Alias: $ mqtt sub
Simple Examples
| Command | Explanation |
|---|---|
mqtt sub -t topic | Subscribe to a topic with default settings and block the console. |
mqtt sub -t test1 -t test2 | Subscribe to the topics ‘test1’ and ‘test2’ with default settings and block the console. |
mqtt sub -t test -h localhost -p 1884 | Subscribe to topic ‘test’ at a broker with the address ‘localhost:1884’. |
Options
Subscribe Options
| Option | Long Version | Explanation | Default |
|---|---|---|---|
-t | --topic | The MQTT topic the client will subscribe to. | |
-q | --qos | Define the quality of service level. If only one QoS is specified it will be used for all topics. You can define a specific QoS level for every topic. The corresponding QoS levels will be matched in order to the given topics. | 0 |
--output-to-file | Append the received publish messages to a file. Creates the file if it does not exist. | ||
--base64 | Whether the received publish messages will be base64 encoded. | false | |
-J | --json-output | Print the received publishes in pretty JSON format. | false |
-T | --show-topics | Prepend the specific topic name to the received publish. | false |
--user-property | A user property of the subscribe message. |
Connect Options
| Option | Long Version | Explanation | Default |
|---|---|---|---|
-h | --host | The MQTT host. | localhost |
-p | --port | The MQTT port. | 1883 |
-V | --mqttVersion | The MQTT version can be set to 3 or 5. | 5 |
-i | --identifier | A unique client identifier can be defined. | A randomly generated UTF-8 String. |
-ip | --identifierPrefix | The prefix for randomly generated client identifiers, if no identifier is given. | mqttClient |
-c | --[no-]cleanStart | Whether the client should start a clean session. | true |
k | --keepAlive | The keep alive of the client (in seconds). | 60 |
-se | --sessionExpiryInterval | The session expiry value in seconds. | 0 (Instant Expiry) |
-Cup | --connectUserProperty | A user property of the connect message. | |
-ws | Use WebSocket transport protocol. | false | |
-ws:path | The path to the WebSocket located at the given broker host. |
Will Options
| Option | Long Version | Explanation | Default |
|---|---|---|---|
-Wd | --willDelayInterval | Will delay interval in seconds. | 0 |
-We | --willMessageExpiryInterval | Lifetime of the will message in seconds. Can be disabled by setting it to 4_294_967_295. | 4_294_967_295 (Disabled) |
-Wm | --willPayload | Payload of the will message. | |
-Wq | --willQualityOfService | QoS level of the will message. | 0 |
-Wr | --willRetain | Retain the will message. | false |
-Wt | --willTopic | Topic of the will message. | |
-Wcd | --willCorrelationData | Correlation data of the will message. | |
-Wct | --willContentType | Description of the will message’s content. | |
-Wpf | --willPayloadFormatIndicator | Payload format can be explicitly specified as UTF8 else it may be UNSPECIFIED. | |
-Wrt | --willResponseTopic | Topic name for a response message. | |
-Wup | --willUserProperties | A user property of the will message. |
Connect Restrictions
| Option | Long Version | Explanation | Default |
|---|---|---|---|
--rcvMax | The maximum amount of not acknowledged publishes with QoS 1 or 2 the client accepts from the server concurrently. | 65535 | |
--sendMax | The maximum amount of not acknowledged publishes with QoS 1 or 2 the client sends to the server concurrently. | 65535 | |
--maxPacketSize | The maximum packet size the client accepts from the server. | 268435460 | |
--sendMaxPacketSize | The maximum packet size the client sends to the server. | 268435460 | |
--topicAliasMax | The maximum amount of topic aliases the client accepts from the server. | 0 | |
--sendTopicAliasMax | The maximum amount of topic aliases the client sends to the server. | 16 | |
--[no-]reqProblemInfo | The client requests problem information from the server. | true | |
--reqResponseInfo | The client requests response information from the server. | false |
Security Options
Credentials Authentication
| Option | Long Version | Explanation | Default |
|---|---|---|---|
-u | --user | Define the username for authentication. | |
-pw | --password | Define the password for authentication directly. If left blank the user will be prompted for the password in the console. | |
-pw:env | Define that the password for authentication is read in from an environment variable. | MQTT_CLI_PW if the option is specified without a value | |
-pw:file | Define the path to a file from which the password is read from. |
TLS Authentication
| Option | Long Version | Explanation | Default |
|---|---|---|---|
-s | --secure | Whether a default (properties file) TLS configuration is used. | false |
--cafile, --ca-cert, --server-cert | The path to the file containing a trusted CA certificate, to enable encrypted certificate based communication. | ||
--capath, --ca-cert-dir, --server-cert-dir | The path to the directory containing trusted CA certificates, to enable encrypted certificate based communication. | ||
--cert, --client-cert | The path to the client certificate to use for client-side authentication. | ||
--key, --client-private-key | The path to the corresponding private key for the given client certificate. | ||
--keypw, --client-private-key-password | The password for the client private key. | ||
--ks, --keystore | The path to the client keystore for client side authentication. | ||
--kspw, --keystore-password | The password for the keystore. | ||
--kspkpw, --keystore-private-key-password | The password for the private key inside the keystore. | ||
--ts, --truststore | The path to the client truststore, to enable encrypted certificate based communication. | ||
--tspw, --truststore-password | The password for the truststore. | ||
--ciphers | The supported cipher suites in IANA string format concatenated by the ‘:’ character, if more than one cipher should be supported. e.g TLS_CIPHER_1:TLS_CIPHER_2 See IANA Format for supported cipher suite strings. | ||
--tls-version | The TLS version to use - TLSv1.1 TLSv1.2 TLSv1.3. | TLSv1.2 |
Logging Options
| Option | Long Version | Explanation | Default |
|---|---|---|---|
-l | Log to ~./mqtt-cli/logs (Configurable through ~/.mqtt-cli/config.properties). | false |
Debug Options
| Option | Long Version | Explanation | Default |
|---|---|---|---|
-d | --debug | Print debug messages to the console. | false |
-v | --verbose | Print trace messages to the console. | false |
Help Options
| Option | Long Version | Explanation |
|---|---|---|
--help | Display help message for command. | |
--version | Display version information of the cli. |
Further Examples
Subscribe to one topic with QoS level Exactly Once.
NOTE: If you specify one QoS and multiple topics, the QoS will be used for all topics.
mqtt sub -t topic1 -t topic2 -q 2
Subscribe to the given topics with a specific QoS for each topic. (topic1 will have QoS 0, topic2 QoS 1 and topic3 QoS 2)
mqtt sub -t topic1 -q 0 -t topic2 -q 1 -t topic3 -q 2
Subscribe to a topic and output the received publish messages to the file publishes.log in the current directory.
NOTE: The MQTT CLI creates the file if it does not exist. Received publish messages will be appended.
mqtt sub -t topic -of publishes.log
Subscribe to a topic and output the received publish messages to the file publishes.log in a specified /usr/local/var directory.
NOTE: The MQTT CLI creates the file if it does not exist. Received publish messages will be appended.
mqtt sub -t topic -of /usr/local/var/publishes.log
Subscribe to a topic and output all the received messages in base64 encoding.
mqtt sub -t topic -b64