---
title: "Use the Kafka CLI terminal"
description: "Open the playground's terminal, run the standard Kafka tools against the simulated cluster, and change the cluster from the command line."
url: https://monedula.dev/flock/docs/kafka-simulator/how-to/use-the-kafka-cli-terminal/
---
The examples run in the free-play sandbox the [playground](/kafka-simulator/playground/) opens with. The [terminal command reference](/flock/docs/kafka-simulator/reference/terminal-commands/) lists every tool, flag and builtin.

## Steps

### 1. Open the terminal

Select the bar along the bottom of the playground, labelled `user@broker-1:~ - kafka-cli`, or press `` Ctrl+` ``. A drawer slides up over the lower part of the screen; drag its title bar to resize it, and double-click the title bar to put it back. On a phone, open **⋯** in the top bar and select **kafka-cli ↗** under **terminal**: the terminal fills the screen, with a row of commands to tap and a **RUN** button.

Each time it opens, the terminal greets you with three lines, then the prompt:

```text
kafka-cli - the Kafka CLI tools against the simulated cluster above. Reads render the frame on screen; changes animate on the canvas.
Start with `help`. You are on broker-1 - `ssh broker-2` moves you; the prompt shows the host (and its region on multi-region clusters).
Ctrl+` toggles this drawer, Esc returns focus to the canvas.
user@broker-1:/var/kafka-logs$
```

The greeting goes away when you run your first command. `help` lists the tools and builtins this release ships.

### 2. Run a read

Describe the sandbox's topic:

```text
kafka-topics --describe --topic orders
```

```text
Topic: orders  PartitionCount: 3  ReplicationFactor: 3  Configs: min.insync.replicas=2,cleanup.policy=delete
	Partition: 0  Leader: 1  Replicas: 1,2,3  Isr: 1,2,3
	Partition: 1  Leader: 2  Replicas: 2,3,1  Isr: 2,3,1
	Partition: 2  Leader: 3  Replicas: 3,1,2  Isr: 3,1,2
```

Then the lag view of the group the canvas labels `cg1`. The tools know it by its id, `c1`, which `kafka-consumer-groups --list` prints:

```text
kafka-consumer-groups --describe --group c1
```

The output has the real tool's columns, `GROUP`, `TOPIC`, `PARTITION`, `CURRENT-OFFSET`, `LOG-END-OFFSET`, `LAG`, `CONSUMER-ID`, `HOST` and `CLIENT-ID`, one row per partition.

### 3. Change the cluster

Set a retention time on the topic:

```text
kafka-configs --alter --entity-type topics --entity-name orders --add-config retention.ms=60000
```

```text
Completed updating config for topic orders.
```

The change is recorded on the timeline like the matching button press, and travels in a [shared link](/flock/docs/kafka-simulator/how-to/share-by-url/).

### 4. Use completion and history

**Tab** completes a tool, a flag or a live name, such as a topic, group, broker or config key, and **↑** and **↓** walk the history. The reference's [Keys table](/flock/docs/kafka-simulator/reference/terminal-commands/#keys) lists the other keys.

### 5. Close it

Press `` Ctrl+` `` again or select **×** in the title bar. Closing keeps the session: the output, the current directory and the history are there when you reopen it. Switching to another scenario starts a fresh session on the new cluster and keeps only the command history.

## Check it worked

Describe the topic's configuration:

```text
kafka-configs --describe --entity-type topics --entity-name orders
```

The list of dynamic configs now includes `retention.ms=60000`.

## Related

- The **Terminal ops** module of the [scenario catalog](/flock/docs/kafka-simulator/reference/scenarios/) has scripted scenarios built around the terminal, such as [Diagnose lag before opening the inspector](/kafka-simulator/playground/?scenario=13.1.2). Their steps show commands as buttons: selecting one opens the terminal with the command typed in, and you press **Enter** to run it.
- The Terminal ops scenarios also have their own pages, such as [Diagnose lag before opening the inspector](/kafka-simulator/scenarios/diagnose-lag/) and [Find the unhealthy partitions](/kafka-simulator/scenarios/unhealthy-partitions/).
- [Kafka partitions are under-replicated](/kafka-simulator/troubleshooting/under-replicated-partitions/) and [Consumer lag keeps growing](/kafka-simulator/troubleshooting/consumer-lag-keeps-growing/) start from what the `--describe` commands report and say what to check next.