# Kafka topics CLI tutorial

*Learn how to manage Kafka topics using the kafka-topics CLI in 10 minutes*

The `kafka-topics` CLI is your primary tool for creating, listing, describing, altering, and deleting Kafka topics.

**What you'll learn:**
- How to create topics with specific partitions and replication factor
- How to list and describe existing topics
- How to alter topic partition count
- How to delete topics

> **Platform extensions**
> Use CLI commands with appropriate extensions for your platform: `.bat` for Windows, `.sh` for Mac and Linux.

## How to create a Kafka topic?

To create a Kafka topic, you need to provide:
- Kafka hostname and port (e.g., `localhost:9092`)
- Topic name
- Number of partitions
- Replication factor

### Example

Creating a topic named `first_topic` with 3 partitions and replication factor of 1:

For Kafka v2.2+:
```bash
kafka-topics --bootstrap-server localhost:9092 --topic first_topic --create --partitions 3 --replication-factor 1
```

### Important gotchas

- Cannot specify a replication factor greater than the number of brokers
- No default values for partitions and replication factor
- Topic name must contain only ASCII alphanumerics, '.', '_' and '-'

## How to list Kafka topics?

Use `kafka-topics` with the `--list` option.

### Example

For Kafka v2.2+:
```bash
kafka-topics --bootstrap-server localhost:9092 --list
```

## How to describe a Kafka topic?

Use `kafka-topics` with the `--describe` option.

### Example

For Kafka v2.2+:
```bash
kafka-topics --bootstrap-server localhost:9092 --describe --topic first_topic
```

## How to increase the number of partitions?

Use `kafka-topics` with the `--alter` option.

> **Caution**: Increasing the number of partitions in a Kafka topic is a DANGEROUS OPERATION if your applications are relying on key-based ordering.

### Example

```bash
kafka-topics --bootstrap-server localhost:9092 --alter --topic first_topic --partitions 5
```

## How to delete a Kafka topic?

Use `kafka-topics` with the `--delete` option.

### Example

```bash
kafka-topics --bootstrap-server localhost:9092 --delete --topic first_topic
```

> Ensure `delete.topic.enable=true` is set on brokers for deletion to work properly.

## Quick reference

| Operation | Command |
|-----------|---------|
| Create topic | `kafka-topics --bootstrap-server localhost:9092 --create --topic NAME --partitions N --replication-factor R` |
| List topics | `kafka-topics --bootstrap-server localhost:9092 --list` |
| Describe topic | `kafka-topics --bootstrap-server localhost:9092 --describe --topic NAME` |
| Add partitions | `kafka-topics --bootstrap-server localhost:9092 --alter --topic NAME --partitions N` |
| Delete topic | `kafka-topics --bootstrap-server localhost:9092 --delete --topic NAME` |

> **See it in practice with Conduktor**
> [Conduktor Console](https://docs.conduktor.io/guide/manage-kafka/kafka-resources/topics) provides a visual interface for topic management. Create, configure, and monitor topics without memorizing CLI syntax.

## Next steps

- [Produce messages](https://www.conduktor.io/kafka/kafka-producer-cli-tutorial) to your new topic with the console producer
- [Consume messages](https://www.conduktor.io/kafka/kafka-consumer-cli-tutorial) from topics
- [Configure topic settings](https://www.conduktor.io/kafka/how-to-change-a-kafka-topic-configuration-using-the-cli) for production