Link Search Menu Expand Document Edit GitHub


The connect command creates a client and connects it to the specified broker. The client will stay connected until it is disconnected by the broker or the disconnect method is called. To list all the connected clients of this mqtt-cli shell session use the list method.

mqtt> connect

Alias: mqtt> con

Simple Examples

mqtt> conCreates and connects a new MQTT client with the default settings.
mqtt> con -V 3 -h myHostCreates and connects an MQTT 3.1.1 client at myHost with the default port.
mqtt> con -i mqtt-client -p 1884Creates and connects an MQTT client at localhost with port 1884 which is identified by mqtt-client.


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.5
-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 is given.mqttClient
-c--[no-]cleanStartWhether the client should start a clean session.true
k--keepAliveThe keep alive of the client (in seconds).60
-se--sessionExpiryIntervalThe session expiry value in seconds.0 (Instant Expiry)
-Cup--connectUserPropertyA 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

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--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--willUserPropertiesA 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 sends 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
 --reqResponseInfoThe client requests response information from the server.false

Security Options

Credentials Authentication

OptionLong VersionExplanationDefault
-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 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

OptionLong VersionExplanationDefault
-s--secureWhether a default (properties file) TLS configuration is used.false
 --cafile, --ca-cert, --server-certThe path to the file containing a trusted CA certificate, to enable encrypted certificate based communication. 
 --capath, --ca-cert-dir, --server-cert-dirThe path to the directory containing trusted CA certificates, to enable encrypted certificate based communication. 
 --cert, --client-certThe path to the client certificate to use for client-side authentication. 
 --key, --client-private-keyThe path to the corresponding private key for the given client certificate. 
 --keypw, --client-private-key-passwordThe password for the client private key. 
 --ks, --keystoreThe path to the client keystore for client side authentication. 
 --kspw, --keystore-passwordThe password for the keystore. 
 --kspkpw, --keystore-private-key-passwordThe password for the private key inside the keystore. 
 --ts, --truststoreThe path to the client truststore, to enable encrypted certificate based communication. 
 --tspw, --truststore-passwordThe password for the truststore. 
 --ciphersThe supported cipher suites in IANA string format concatenated by the ‘:’ character, if more than one cipher should be supported.
See IANA Format for supported cipher suite strings.
 --tls-versionThe TLS version to use - TLSv1.1 TLSv1.2 TLSv1.3.TLSv1.2

Help Options

OptionLong VersionExplanation
 --helpDisplay help message for command.
 --versionDisplay version information of the cli.


Connect a client to myHost on port 1884

mqtt> con -h myHost -p 1884

Connect a client to the default host and port using authentication

mqtt> con -u username -pw password
# Or omit the password to get it prompted
mqtt> con -u username -P
Enter value for --password (The password for the client UTF-8 String.):

Connect a client with default settings and use it to publish

mqtt> con -i myClient
myClient@localhost> pub -t test -m "Hello World"

Connect a client with a will message

mqtt> con -wt willtopic -wq 2 -wm "Client disconnected ungracefully"

Connect a client with SSL using client side and server side authentication with a password encrypted private key

mqtt> con --cafile pathToServerCertificate.pem --tls-version TLSv.1.3
         --cert pathToClientCertificate.pem --key pathToClientKey.pem
Enter private key password:

Connect a client which is identified by myClient and disconnect it afterward using default settings

mqtt> con -i myClient
myClient@localhost> dis

Connect a client which is identified by myClient on specific settings and disconnect it afterward

mqtt> con -i myClient -h -V 3
myClient@localhost> exit  # client is still connected
mqtt> dis -i myClient -h

NOTE: When specifying the identifier in order to uniquely identify the desired client, the hostname must also be provided. If you don’t specify these, the default settings for these attributes will be used which may lead to unexpected behavior.