Before defining the tool precisely, it helps to see the everyday need it fills.

Sometimes you just want to look

A consumer is any program that reads events from a Kafka topic, a named stream of related events. Building a full consumer application, with its own code, configuration, and deployment process, is exactly the right approach for a real, ongoing piece of business logic. But it is a lot of unnecessary effort just to answer a quick question like “is any data actually flowing into this topic right now” or “what does a typical event in this topic actually look like”.

This is a situation almost every engineer working with Kafka runs into constantly, especially while learning, testing, or troubleshooting. Writing and running a custom application every single time would slow everyone down considerably.

A tool built specifically for this everyday need

Kafka ships with a small collection of command-line tools specifically for tasks like this, and kafka-console-consumer.sh is the one built for quickly reading and displaying events from a topic directly in a terminal window, the text-based interface many engineers use to run commands on a computer.

A precise definition, then the plain-English version.

A short definition

kafka-console-consumer.sh is a command-line script included with Apache Kafka that acts as a simple, ready-made consumer, connecting to a Kafka cluster, reading events from a chosen topic, and printing them out directly to your terminal window as plain text, one after another, as they are read.

In everyday terms, it is a small, disposable consumer you can start up in seconds, watch for as long as you like, and shut down the moment you have seen what you needed to see, without writing, compiling, or deploying any application code at all.

Why the name looks the way it does

The name breaks down quite literally. “Kafka” identifies which system this tool belongs to. “Console” refers to the terminal, or console, where its output appears. “Consumer” describes exactly what it does, consuming, meaning reading, events from a topic. The “.sh” ending simply indicates it is a shell script, a small program written to be run directly from a command-line terminal.

Before it can do anything useful, this tool needs to know two basic things.

Without these, it cannot do its job

Just like a delivery driver needs both an address and a specific parcel to deliver, this tool cannot meaningfully start without knowing exactly which cluster to talk to and exactly which topic within that cluster it should be watching. Every other option available on this tool builds on top of these two essential pieces of information.

One of the very first practical choices you make when running this tool.

Only new events, by default

Without being told otherwise, kafka-console-consumer.sh generally only shows events published from the moment it starts running onward. Anything that was already sitting in the topic before you started watching will simply not appear, since the tool begins reading from the latest available point by default.

Choosing to see everything from the start

The tool also offers a setting to instead begin reading from the very earliest available event still retained in the topic, effectively showing you the topic’s full existing history, within whatever retention period, a setting controlling how long data is kept, that topic is currently configured with.

Understanding exactly what you are looking at once events start appearing.

The value, by default

By default, this tool typically prints just the value, the main content, of each event it reads, with each one shown on its own new line as it arrives, giving a simple, scrolling view of the topic’s activity over time.

Choosing to see the key as well

The tool also offers a setting to additionally print each event’s key, an identifying label often used for routing and grouping, alongside its value. This is especially useful when trying to understand how a topic’s data is actually organised, or when checking whether related events are sharing the same key as expected.

Sometimes you want a narrower, more focused view than the entire topic.

Focusing on just one slice

A topic is often split into smaller pieces called partitions, each an independently ordered slice of the topic’s overall data. This tool offers a setting to focus specifically on just one chosen partition, rather than reading across every partition of the topic at once.

Why you might want this

This narrower view can be especially useful while troubleshooting, such as when a team suspects a problem is affecting only certain events, and those events are known to always land on a particular partition because they share a specific key, an identifying label that consistently maps to that one partition.

A small but genuinely handy setting for quick, one-off checks.

Watching indefinitely, by default

Left to its own devices, this tool will keep running and printing new events indefinitely, until the person running it manually stops it, typically by pressing a specific interrupt key combination in the terminal.

Setting a limit instead

The tool also offers a setting to automatically stop itself after printing a specific number of events, which is especially convenient for a quick sanity check, such as confirming that a handful of recent events look roughly as expected, without needing to watch and manually stop it yourself.

An important, practical question with a slightly nuanced answer.

By default, a temporary, throwaway identity

A consumer group is a named team of consumers sharing the work of reading a topic, with its reading progress durably tracked. Unless told otherwise, this tool typically connects using a randomly generated, temporary consumer group identity each time it runs, meaning it does not meaningfully build up any lasting, durable reading progress you would rely on later.

Explicitly joining a named group

The tool also allows you to specify an actual, named consumer group if desired, causing it to behave much more like a genuine, ongoing consumer, tracking and committing its offsets, numbers marking its exact reading position, just as a real application consumer would.

This tool rarely works entirely alone; it usually has a natural counterpart.

The producer side of the same idea

Kafka also ships with a companion tool, commonly named kafka-console-producer.sh, which lets an engineer type text directly into a terminal and publish it as events into a chosen topic. Together, these two simple tools let someone quickly send a test event with one tool and immediately watch it arrive with the other, entirely from the command line.

Tools for managing topics themselves

Kafka additionally provides other command-line tools focused on managing topics directly, such as creating a new topic, listing existing ones, or inspecting a topic’s current configuration and partition details, rounding out a small but genuinely useful toolkit for everyday, hands-on Kafka work.

flowchart LR
  Prod["kafka-console-producer.sh"] -->|publishes test event| Topic[Kafka Topic]
  Topic -->|read live| Cons["kafka-console-consumer.sh"]
        

A genuinely handy tool, but not without its limits.

Seeing a few concrete examples brings the whole idea to life.

Practical lessons for using this tool comfortably and safely.

Best practices

Mistakes beginners often make

No. It is a ready-made command-line tool. You simply provide it with the cluster address and the topic name you want to watch, along with any optional settings you choose.

By default, the tool only shows events published from the moment it starts onward. To see a topic’s existing history, you need to explicitly choose to start reading from the earliest available point instead.

Generally, yes, since reading a topic does not remove or change its data. The main caution is around consumer group usage, avoiding reusing a real application’s named group to prevent interfering with its tracked progress.

Yes. The tool offers a setting to display each event’s key alongside its value, which is useful for confirming how data is grouped or routed within a topic.

Since it runs indefinitely by default, it is typically stopped manually using a standard terminal interrupt key combination, or automatically if a maximum number of events to display has been configured in advance.

Yes. A setting lets you focus on a single chosen partition, rather than reading across an entire topic’s partitions at once, which is useful for narrower, more focused troubleshooting.

Yes. A companion tool, commonly named kafka-console-producer.sh, lets you type text directly into a terminal and publish it as events, making it easy to pair with the console consumer for quick, hands-on experiments.

kafka-console-consumer.sh is a small, ready-made command-line tool, shipped directly with Kafka, that lets anyone quickly connect to a cluster, read events from a chosen topic, and see them printed right in their terminal, all without writing or deploying any application code. With just a cluster address and a topic name as its essential starting point, it offers a handful of genuinely useful settings, choosing where reading starts, whether keys are shown, which partition to focus on, and when to automatically stop, that together make it a natural first stop for learning, testing, and troubleshooting Kafka topics. While it is never meant to replace a properly built consumer application, its simplicity and immediacy make it one of the most frequently reached-for tools in everyday, hands-on Kafka work.