Kafka CLI Tools

Every Kafka distribution ships with a bin/ directory full of shell scripts that talk to your cluster over the same protocol your applications use. Long before you write a line of producer code, these tools let you create topics, push and tail messages, inspect consumer lag, and tweak broker and topic configuration live. Mastering them pays off daily — they are the fastest way to reproduce a bug, verify a deployment, or answer “is the data actually flowing?” in production. This page is a reference-style tour of the scripts you will reach for most.

Every example below targets a KRaft-mode broker listening on the default localhost:9092. On Linux and macOS the scripts end in .sh; on Windows use the equivalent .bat files under bin/windows.

Managing topics with kafka-topics

kafka-topics.sh is the workhorse for the full topic lifecycle: create, list, describe, alter, and delete. Almost every invocation needs --bootstrap-server to point at a broker.

Create a topic with an explicit partition count and replication factor:

kafka-topics.sh --bootstrap-server localhost:9092 \
  --create --topic orders \
  --partitions 3 --replication-factor 1

Output:

Created topic orders.

List all topics, then describe one to see its partition layout, leaders, and in-sync replicas (ISR):

kafka-topics.sh --bootstrap-server localhost:9092 --list
kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic orders

Output:

orders
Topic: orders   TopicId: 7Hk3...   PartitionCount: 3   ReplicationFactor: 1   Configs:
        Topic: orders   Partition: 0    Leader: 1   Replicas: 1   Isr: 1
        Topic: orders   Partition: 1    Leader: 1   Replicas: 1   Isr: 1
        Topic: orders   Partition: 2    Leader: 1   Replicas: 1   Isr: 1

You can only increase partitions, never decrease them, because shrinking would break key-to-partition mapping:

kafka-topics.sh --bootstrap-server localhost:9092 \
  --alter --topic orders --partitions 6

Delete a topic when you are done (this is irreversible):

kafka-topics.sh --bootstrap-server localhost:9092 --delete --topic orders

Adding partitions changes which partition a given key hashes to. If your application relies on per-key ordering, repartitioning a live topic will scatter a key’s history across partitions. Plan partition counts up front.

Producing and consuming from the console

kafka-console-producer.sh reads stdin line by line and sends each line as a message value. It is perfect for hand-feeding test data:

kafka-console-producer.sh --bootstrap-server localhost:9092 --topic orders
>order-1
>order-2

To send keys as well as values, enable key parsing and pick a separator:

kafka-console-producer.sh --bootstrap-server localhost:9092 --topic orders \
  --property "parse.key=true" --property "key.separator=:"
>cust-42:order-1

kafka-console-consumer.sh tails a topic. By default it reads only messages produced after it starts; add --from-beginning to replay the whole log, and --property print.key=true to show keys:

kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic orders \
  --from-beginning --property print.key=true --property key.separator=" => "

Output:

cust-42 => order-1
null => order-2

Pass --group to consume as part of a named consumer group, which commits offsets so a later run resumes where this one left off:

kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic orders \
  --group cli-readers

Inspecting consumer groups and lag

kafka-consumer-groups.sh is how you diagnose the single most common Kafka question in production: “are my consumers keeping up?” The --describe action reports, per partition, the latest offset (LOG-END-OFFSET), the committed offset (CURRENT-OFFSET), and the difference (LAG).

kafka-consumer-groups.sh --bootstrap-server localhost:9092 \
  --describe --group cli-readers

Output:

GROUP       TOPIC   PARTITION  CURRENT-OFFSET  LOG-END-OFFSET  LAG  CONSUMER-ID      HOST         CLIENT-ID
cli-readers orders  0          12              15              3    consumer-1-abc   /127.0.0.1   consumer-1
cli-readers orders  1          8               8               0    consumer-1-abc   /127.0.0.1   consumer-1
cli-readers orders  2          20              20              0    consumer-1-abc   /127.0.0.1   consumer-1

Sustained, growing lag means consumers are falling behind. To replay or skip messages, use --reset-offsets. Always run with --dry-run first to preview, then --execute to apply — and stop the group’s consumers, because offsets cannot be reset while members are active:

kafka-consumer-groups.sh --bootstrap-server localhost:9092 \
  --group cli-readers --topic orders \
  --reset-offsets --to-earliest --execute

Reset option	Effect
--to-earliest	Jump to the start of the log (full replay)
--to-latest	Skip everything, only read new messages
--to-offset N	Move to a specific offset
--shift-by N	Move forward (+) or back (-) N messages
--to-datetime <ISO>	Reset to the first offset at or after a timestamp

List all groups with --list, and remove a defunct one with --delete --group <name>.

Reading and changing configuration

kafka-configs.sh reads and dynamically alters configuration on topics, brokers, and clients — many changes apply without a restart. Inspect a topic’s effective settings:

kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type topics --entity-name orders --describe

Add a seven-day retention policy and a cleanup mode:

kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type topics --entity-name orders \
  --alter --add-config retention.ms=604800000,cleanup.policy=delete

Remove an override to fall back to the broker default:

kafka-configs.sh --bootstrap-server localhost:9092 \
  --entity-type topics --entity-name orders \
  --alter --delete-config retention.ms

Querying offsets directly

kafka-get-offsets.sh reports partition offsets without joining a consumer group — handy for monitoring scripts and capacity checks. The --time flag accepts -1 for the latest offset, -2 for the earliest, or a millisecond timestamp:

kafka-get-offsets.sh --bootstrap-server localhost:9092 \
  --topic orders --time -1

Output:

orders:0:15
orders:1:8
orders:2:20

The earliest and latest offsets together tell you exactly how many records currently live in each partition.

Best Practices

• Always pass --bootstrap-server; the older --zookeeper flag is gone in modern KRaft clusters.
• Run --reset-offsets with --dry-run before --execute, and stop the consumer group first — active members block the reset.
• Prefer kafka-configs.sh dynamic overrides for tuning retention and cleanup instead of editing static broker properties and restarting.
• Use kafka-consumer-groups.sh --describe as your first lag-diagnosis step; alert on sustained growth in the LAG column.
• Treat the console producer and consumer as test and debugging tools, not load generators — use kafka-producer-perf-test.sh for benchmarking.
• Never decrease partition counts; size topics for peak fan-out at creation time, since repartitioning reshuffles key placement.

Related Topics

• Installation
• Your First Application
• Kafka Architecture Overview
• Core Concepts Glossary