# Kafka consumer CLI tutorial

*Learn how to consume messages from Kafka using kafka-console-consumer in 10 minutes*

The `kafka-console-consumer` CLI reads data from Kafka topics and outputs it to standard output. It's essential for testing, debugging, and verifying message delivery.

**What you'll learn:**
- How to consume messages from a topic
- How to read historical vs real-time messages
- How to display keys, timestamps, and metadata
- Common consumer options and troubleshooting

> Use CLI commands with appropriate extensions for your platform: for Windows - `kafka-console-consumer.bat`, for Mac and Linux - `kafka-console-consumer.sh`.

## How to consume data in a Kafka topic using the CLI?

To consume data from a Kafka topic, we need to provide the mandatory parameters:

*   Find your Kafka hostname and port e.g., `localhost:9092`
*   Provide the mandatory parameters: topic name
*   If you need to read historical data, use the `--from-beginning` option
*   Otherwise, you will only be reading future data
*   Use the `kafka-console-consumer.sh` CLI

> **Important recommendation: do NOT use the `--zookeeper` option**
> Since Kafka v0.10, the consumer is leveraging a Kafka connection string, not Zookeeper. This is due to how consumer offsets are stored. Any tutorial you see using the `--zookeeper` option should be considered **outdated.**

### Example

Make sure you have followed the [Kafka producer CLI tutorial](https://www.conduktor.io/kafka/kafka-producer-cli-tutorial) to create and send data to a Kafka topic first.

**Consuming only the future messages of a Kafka topic**

```
kafka-console-consumer --bootstrap-server localhost:9092 --topic first_topic
```

**Consuming all historical messages and future ones in a Kafka topic**

Use the `--from-beginning` option

```
kafka-console-consumer --bootstrap-server localhost:9092 --topic first_topic --from-beginning
```

To exit the Kafka console consumer, use the keyboard combination `Ctrl+C`.

### Command output

```
Hello World
My name is Conduktor
I love Kafka
^CProcessed a total of 3 messages  (<-- when doing a Ctrl+C to exit)
```

The Kafka console consumer will remain opened until you exit it, and will keep on displaying messages to the screen. It assumes all the messages coming in can be deserialized as text (`String`).

By default, the Kafka console consumer does not show the key, or any partition information.

If you do not see any output but you know your Kafka topic has data in it, don't forget to use the `--from-beginning` option.

> **Important note on message ordering**
> The order of messages is not total, it is per partition. As a topic may be created with more than one partition, the order is only guaranteed at the partition level. If you try with only one partition, you will see total ordering.

### Gotchas

Here are the common mistakes and caveats with the `kafka-console-consumer.sh` command:

Messages by default will not display the key or metadata information (see below for how to do it).

*   When you start a `kafka-console-consumer`, unless specifying the `--from-beginning` option, only future messages will be displayed and read
*   If the topic does not exist, the console consumer will automatically create it with default settings
*   You can consume multiple topics at a time with a comma-delimited list or a pattern
*   If a consumer group id is not specified, the `kafka-console-consumer` generates a random consumer group
*   If messages do not appear in order, remember that the order is at the partition level, not at the topic level

### Extra important options you can set (advanced)

`--from-beginning`

We won't repeat this one enough. To read all historical messages

`--formatter`

To display messages in a particular format (example below to display keys)

`--consumer-property`

To pass in any consumer property, such as the `allow.auto.create.topics` setting

`--group`

By default a random consumer group ID is chosen, but you can override it with this option. See the demo in the [Kafka consumers in group CLI tutorial](https://www.conduktor.io/kafka/kafka-consumers-in-group-cli-tutorial).

`--max-messages`

Number of messages to consume before exiting

`--partition`

If you want to only consume from a specific partition.

## How to consume a Kafka topic and show both the key and value using the Kafka console consumer CLI?

By default, the console consumer will show only the value of the Kafka record. Using this command you can show both the key and value.

Using the `formatter` `kafka.tools.DefaultMessageFormatter` and using the properties `print.timestamp=true` `print.key=true` `print.value=true`:

```
kafka-console-consumer --bootstrap-server localhost:9092 --topic first_topic --formatter kafka.tools.DefaultMessageFormatter --property print.timestamp=true --property print.key=true --property print.value=true --from-beginning

CreateTime:1641810588071	null	hello
CreateTime:1641823304170	name	Stephane
CreateTime:1641823301294	example key	example value
```

More properties are available such as:

*   `print.partition`
*   `print.offset`
*   `print.headers`
*   `key.separator`
*   `line.separator`
*   `headers.separator`

## Quick reference

| Operation | Command |
|-----------|---------|
| Consume new messages | `kafka-console-consumer --bootstrap-server localhost:9092 --topic NAME` |
| Consume all messages | `... --from-beginning` |
| Show keys | `... --property print.key=true` |
| Show all metadata | `... --property print.timestamp=true --property print.key=true --property print.partition=true --property print.offset=true` |
| Limit messages | `... --max-messages 10` |
| Specific partition | `... --partition 0` |

> **See it in practice with Conduktor**
> [Conduktor Console](https://docs.conduktor.io/guide/manage-kafka/kafka-resources/topics) provides a visual interface for consuming messages with built-in deserialization, filtering, and search capabilities.

## Next steps

- [Run consumers in a group](https://www.conduktor.io/kafka/kafka-consumers-in-group-cli-tutorial) to see partitions distribute across consumers
- [Manage consumer group offsets](https://www.conduktor.io/kafka/kafka-consumer-group-management-cli-tutorial) with kafka-consumer-groups
- [Understand consumer concepts](https://www.conduktor.io/kafka/kafka-consumers) in depth