amqtt/docs/references/amqtt_sub.md

# amqtt_sub

`amqtt_sub` is a command line MQTT client that subscribes to some topics and output data received from messages published.

## Usage

`amqtt_sub` usage:

```
amqtt_sub --version
amqtt_sub (-h | --help)
amqtt_sub --url BROKER_URL -t TOPIC... [-n COUNT] [-c CONFIG_FILE] [-i CLIENT_ID] [-q | --qos QOS] [-d]
           [-k KEEP_ALIVE] [--clean-session] [--ca-file CAFILE] [--ca-path CAPATH] [--ca-data CADATA]
           [ --will-topic WILL_TOPIC [--will-message WILL_MESSAGE] [--will-qos WILL_QOS] [--will-retain] ]
           [--extra-headers HEADER]
```

Note that for simplicity, `amqtt_sub` uses mostly the same argument syntax as [mosquitto_sub](http://mosquitto.org/man/mosquitto_sub-1.html).

## Options

- `--version` - amqtt version information
- `-h, --help` - Display `amqtt_sub` usage help
- `-c` - Set the YAML configuration file to read and pass to the client runtime.
- `-d` - Enable debugging information.
- `--ca-file` - Define the path to a file containing PEM encoded CA certificates that are trusted. Used to enable SSL communication.
- `--ca-path` - Define the path to a directory containing PEM encoded CA certificates that are trusted. Used to enable SSL communication.
- `--ca-data` - Set the PEM encoded CA certificates that are trusted. Used to enable SSL communication.
- `--clean-session` - If given, set the CONNECT clean session flag to True.
- `-i` - The id to use for this client. If not given, defaults to `amqtt_sub/` appended with the process id and the hostname of the client.
- `-k` - Set the CONNECT keep alive timeout.
- `-n` - Number of messages to read before ending. Read forever if not given.
- `-q, --qos` - Specify the quality of service to use for receiving messages. This QoS is sent in the subscribe request.
- `-t` - Topic filters to subscribe.
- `--url` - Broker connection URL, conforming to [MQTT URL scheme](https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme).
- `--will-topic` - The topic on which to send a Will, in the event that the client disconnects unexpectedly.
- `--will-message` - Specify a message that will be stored by the broker and sent out if this client disconnects unexpectedly. This must be used in conjunction with `--will-topic`.
- `--will-qos` - The QoS to use for the Will. Defaults to 0. This must be used in conjunction with `--will-topic`.
- `--will-retain` - If given, if the client disconnects unexpectedly the message sent out will be treated as a retained message. This must be used in conjunction with `--will-topic`.
- `--extra-headers` - Specify a JSON object string with key-value pairs representing additional headers that are transmitted on the initial connection, but only when using a websocket connection

## Configuration

If `-c` argument is given, `amqtt_sub` will read specific MQTT settings for the given configuration file. This file must be a valid [YAML](http://yaml.org/) file which may contain the following configuration elements:

- `keep_alive`: Keep-alive timeout sent to the broker. Defaults to `10` seconds.
- `ping_delay`: Auto-ping delay before keep-alive timeout. Defaults to 1. Setting to `0` will disable to 0 and may lead to broker disconnection.
- `default_qos`: Default QoS for messages published. Defaults to 0.
- `default_retain`: Default retain value to messages published. Defaults to `false`.
- `auto_reconnect`: Enable or disable auto-reconnect if connection with the broker is interrupted. Defaults to `false`.
- `reconnect_retries`: Maximum reconnection retries. Defaults to `2`. Negative value will cause client to reconnect infinitely.
- `reconnect_max_interval`: Maximum interval between 2 connection retry. Defaults to `10`.

## Examples

Examples below are adapted from [mosquitto_sub](http://mosquitto.org/man/mosquitto_sub-1.html) documentation.

Subscribe with QoS 0 to all messages published under $SYS/:

```bash
amqtt_sub --url mqtt://localhost -t '$SYS/#' -q 0
```

Subscribe to 10 messages with QoS 2 from /#:

```bash
amqtt_sub --url mqtt://localhost -t # -q 2 -n 10
```

Subscribe with QoS 0 to all messages published under $SYS/ over mqtt encapsulated in a websocket connection and additional headers:

```bash
amqtt_sub --url wss://localhost -t '$SYS/#' -q 0 --extra-headers '{"Authorization": "Bearer <token>"}'
```