Connect

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

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

Options

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

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`

Help Options

Option	Long Version	Explanation
	`--help`	Display help message for command.
	`--version`	Display version information of the cli.

Examples

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
mqtt>

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

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

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.