Link Search Menu Expand Document

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.

Simple Examples

CommandExplanation
mqtt sub -t topicSubscribe to a topic with default settings and block the console.
mqtt sub -t test1 -t test2Subscribe to the topics ‘test1’ and ‘test2’ with default settings and block the console.
mqtt sub -t test -h localhost -p 1884Subscribe to topic ‘test’ at a broker with the address ‘localhost:1884’.

Synopsis

mqtt sub    -t <topics> [-t <topics>]... 
            [-q <qos>]... 
            [-of <receivedMessagesFile>] 
            [-b64]
            [-J]
            [-T]
            [-up <userProperties>]... 
            [-cdsvl]
            [-h <host>] 
            [-p <port>]                                         
            [-V <version>] 
            [-i <identifier>] 
            [-ip <identifierPrefix>]
            [-k <keepAlive>]  
            [-se <sessionExpiryInterval>]      
            [-Cup <connectUserProperties>]...
            [-ws]
            [-ws:path <webSocketPath>] 
            [-u <user>] 
            [-pw [<password>]]
            [-pw:env [<environmentVariable>]]
            [-pw:file FILE]
            [--cert <clientCertificate>] 
            [--key <clientPrivateKey>]             
            [--cafile FILE]... 
            [--capath DIR]... 
            [--ciphers <cipherSuites>[:<cipherSuites>...]]... 
            [--tls-version <supportedTLSVersions>]... 
            [-Wd <willDelayInterval>] 
            [-We <willMessageExpiryInterval>] 
            [-Wm <willMessage>] 
            [-Wq <willQos>]   
            [-Wr] 
            [-Wt <willTopic>] 
            [-Wcd <willCorrelationData>]
            [-Wct <willContentType>] 
            [-Wpf <willPayloadFormatIndicator>]
            [-Wrt <willResponseTopic>] 
            [-Wup <willUserProperties>]...
            [--rcvMax <receiveMaximum>] 
            [--sendMax <sendMaximum>]
            [--maxPacketSize <maximumPacketSize>] 
            [--sendMaxPacketSize <sendMaximumPacketSize>] 
            [--topicAliasMax <topicAliasMaximum>] 
            [--sendTopicAliasMax <sendTopicAliasMaximum>]                                                                                  
            [--[no-]reqProblemInfo] 
            [--[no-]reqResponseInfo] 
            [--help] 
            [--version]

Subscribe Options

OptionLong VersionExplanationDefault
-t--topicThe MQTT topic the client will subscribe to. 
-q--qosDefine 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
-of--outputToFileIf a file is given print the received publishes to the specified output file. If the file is not present it will be created. 
-b64--base64Whether the received publish messages will be base64 encoded.False
-J--jsonOutputPrint the received publishes in pretty JSON format.False
-T--showTopicsPrepend the specific topic name to the received publish.False
-up--userPropertyA user property of the subscribe message. 

Connect Options

OptionLong VersionExplanationDefault
-h--hostThe MQTT host.localhost
-p--portThe MQTT port.1883
-V--mqttVersionThe MQTT version can be set to 3 or 5.MQTT v.5.0
-i--identifierA unique client identifier can be defined.A randomly generated UTF-8 String.
-ip--identifierPrefixThe prefix for randomly generated client identifiers, if no identifier given.mqttClient
-c--[no-]cleanStartWhether the client should start a clean session.True
k--keepAliveThe keep alive of the client (in seconds)60
-se--sessionExpiryIntervalSession expiry value in seconds.0 (Instant Expiry)
-Cup--connectUserPropertyA user property of the subscribe message. 
--ws Use WebSocket transport protocol.False
--ws:path The path to the WebSocket located at given broker host. 
-l Log to ~./mqtt.cli/logs (Configurable through ~/.mqtt-cli/config.properties)false

Security Options

OptionLong VersionExplanationDefault
-s--secureWhether a default SSL configuration is used.False
-u--userDefine the username for authentication. 
-pw--passwordDefine the password for authentication directly.
If left blank the user will be prompted for the password in console.
 
-pw:env Define that the password for authentication is read in from an environment variable.MQTT_CLI_PW if option is specified without value
-pw:file Define the path to a file from which the password is read in. 
 --certThe path to the client certificate to use for client-side authentication. 
 --keyThe path to the corresponding private key for the given client certificate. 
 --cafileThe path to the file containing a trusted CA certificate to enable encrypted certificate based communication. 
 --capathThe path to the directory containing trusted CA certificates to enable encrypted certificate based communication. 
 --ciphersThe 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-versionThe TLS version to use - TLSv1.1 TLSv1.2 TLSv1.3TLSv1.2

Will Options

OptionLong VersionExplanationDefault
-Wd--willDelayIntervalWill delay interval in seconds.0
-We--willMessageExpiryIntervalLifetime of the will message in seconds.
Can be disabled by setting it to 4_294_967_295
4_294_967_295 (Disabled)
-Wm--willPayloadPayload of the will message. 
-Wq--willQualityOfServiceQoS level of the will message.0
-Wr--[no-]willRetainRetain the will message.False
-Wt--willTopicTopic of the will message. 
-Wcd--willCorrelationDataCorrelation data of the will message 
-Wct--willContentTypeDescription of the will message’s content. 
-Wpf--willPayloadFormatIndicatorPayload format can be explicitly specified as UTF8 else it may be UNSPECIFIED. 
-Wrt--willResponseTopicTopic Name for a response message. 
-Wup--willUserPropertyA user property of the will message. 

Connect Restrictions

OptionLong VersionExplanationDefault
 --rcvMaxThe maximum amount of not acknowledged publishes with QoS 1 or 2 the client accepts from the server concurrently.65535
 --sendMaxThe maximum amount of not acknowledged publishes with QoS 1 or 2 the client send to the server concurrently.65535
 --maxPacketSizeThe maximum packet size the client accepts from the server.268435460
 --sendMaxPacketSizeThe maximum packet size the client sends to the server.268435460
 --topicAliasMaxThe maximum amount of topic aliases the client accepts from the server.0
 --sendTopicAliasMaxThe maximum amount of topic aliases the client sends to the server.16
 --[no-]reqProblemInfoThe client requests problem information from the server.true
 --[no-]reqResponseInfoThe client requests response information from the server.false

Further Examples

Subscribe to one topic with default QoS 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: If the file is not created yet it will be created by the CLI. If it is present the received publish messages will be appended to the file.

$ 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: If the file is not created yet it will be created by the CLI. If it is present the received publish messages will be appended to the file.

$ 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

Table of contents