---
title: "Terminal commands"
description: "Every Kafka tool, flag and builtin the playground's terminal accepts, and what each one does against the simulated cluster."
url: https://monedula.dev/flock/docs/kafka-simulator/reference/terminal-commands/
---
The terminal's tools follow the real ones' flags and output, pinned to Apache Kafka 4.3, for the subset listed here. [Use the Kafka CLI terminal](/flock/docs/kafka-simulator/how-to/use-the-kafka-cli-terminal/) shows how to open it and run a first command.

## How the terminal reads a command

- **Quoting.** Single and double quotes group words, so a JSON argument goes in single quotes. A flag value can follow the flag, `--topic orders`, or be joined to it, `--topic=orders`.
- **No shell.** There are no pipes, redirections, wildcards or variables: `|` and `>` are ordinary words.
- **Repeated flags.** When a flag is given twice, the last value wins. `kafka-console-producer --property` is the exception and keeps every value.
- **`--bootstrap-server` and `--command-config`.** Every Kafka tool except `kafka-server-stop` and `kafka-server-start` accepts `--bootstrap-server`. An address of a broker in another region, such as `broker-3:9092`, runs the command against that region's cluster; any other address is accepted and ignored. `kafka-topics`, `kafka-consumer-groups`, `kafka-configs`, `kafka-reassign-partitions`, `kafka-leader-election`, `kafka-console-consumer` and `kafka-transactions` also accept `--command-config`.
- **The current host decides the cluster.** On a two-region topology, a tool talks to the cluster of the broker you are logged into.
- **Reads use the frame on screen.** A read shows the cluster at the frame you are looking at, so pausing or stepping back the timeline lets you inspect any earlier moment.
- **Changes go through the playground.** A command that changes the cluster takes the same path as the matching button. It is recorded and travels in a shared link, and in a scripted scenario the first one forks the scenario into a sandbox.
- **Help.** Every tool this release ships answers `--help` with its usage, and `man <tool>` prints the same.
- **Errors.** An unknown flag prints `unrecognized option '--name'`. Any `--zookeeper` flag prints a hint that it was removed in Kafka 4.x, in favor of `--bootstrap-server`. An unknown command prints `bash: <command>: command not found` and the list of tools.
- **Later releases.** `help`, **Tab** completion, the faint suggestion and the tool list in the command-not-found message show only the tools this release ships. Typing a tool from a later release, or `man` for it, prints a one-line notice instead, naming the version that brings it and pointing at the changelog: `<tool> is available in v<version> - see the changelog`. A tool with no release version yet reads `available in preview builds` in place of the version.

## Keys

| Key | What it does |
| --- | --- |
| `` Ctrl+` `` | Opens or closes the terminal. |
| **Enter** | Runs the line. |
| **Tab** | Completes a tool, a flag, a builtin, a host, a path or a live name: a topic, group, broker or config key. |
| **→** | At the end of the line, accepts the faint suggestion after the cursor: a match from your history, or the only possible completion. |
| **↑**, **↓** | Walk the command history, kept for the browser session, up to 200 commands. |
| **Ctrl+C** | Cancels the line, stops a `watch` or a console consumer, or leaves console-producer mode. |
| **Ctrl+D** | Leaves console-producer mode. |
| **Ctrl+L** | Clears the screen. |
| **Esc** | Takes the focus off the terminal. |

## Builtins

| Command | What it does |
| --- | --- |
| `help` | Lists the tools, the builtins and the disk view commands. |
| `clear` | Clears the screen. |
| `man <page>` | `man <tool>` prints the tool's usage; `man kafka` prints a short overview. |
| `history` | Lists the commands you ran, numbered. |
| `watch [-n secs] <command>` | Re-runs a read on every displayed frame and replaces its output in place, until **Ctrl+C**. The timeline is its only clock, so pausing freezes it; `-n` only sets the interval in its header, 2 seconds by default. It refuses a command that changes the cluster, and `ssh`, `exit`, `cd`, `clear` and `watch` itself. |
| `ssh <host>` | Logs into a broker or a controller and moves to its home directory. It refuses an unknown host, a host that is down (`Connection refused`) and a host the current one cannot reach across a network partition (`No route to host`). |
| `exit` | Returns to the previous host. On the first host it prints `logout` and stays. |
| `hostname` | Prints the current host. |
| `ping <host>` | Sends one packet from the current host: it is answered, lost because the host is down, or reported as `Destination Host Unreachable` across a network partition. |

The prompt shows where you are: `user@broker-1:/var/kafka-logs$`, with the region in brackets on a two-region topology, as in `user@broker-3 [dr]`. The terminal starts on the lowest-numbered live broker. If the host you are on goes down, the next command prints `Connection to broker-1 closed by remote host.` and moves you to the lowest-numbered live broker. You can also change host from the menu on the terminal's title bar, or by holding **Alt** and selecting a broker on the canvas.

## Disk view

Each broker has a read-only `/var/kafka-logs` with one directory per partition replica it holds, such as `orders-0`. A directory holds segment files, `.log`, `.index` and `.timeindex`, plus `leader-epoch-checkpoint` and `partition.metadata`. The files are a projection of the cluster, at a teaching scale: a segment rolls every 4 records, and a record counts as 1 KiB.

| Command | What it does |
| --- | --- |
| `pwd`, `cd <dir>` | Prints or changes the current directory. |
| `ls [-l] [-h] [path]` | Lists a directory; `-l` adds sizes and times from the simulated clock. |
| `tree [-L n]` | Prints the directory tree, `n` levels deep. |
| `du [-sh] <path>` | Disk use of a directory or file. |
| `df [-h]` | Disk use of the whole log directory. |
| `cat <file>` | Prints `leader-epoch-checkpoint`, `partition.metadata`, or `config/server.properties` (on a controller, `config/controller.properties`) built from the topology. A `.log` file answers that it is binary. |
| `kafka-dump-log --files <file> [--print-data-log]` | Decodes a `.log` segment: each batch's offsets, record count, producer id and whether it is transactional. `--print-data-log` adds each record's offset, key and payload. |
| `ls remote://bucket/` | Lists the segments tiered storage has moved off this broker. |
| `rm`, `touch`, `mkdir`, `rmdir`, `mv`, `cp`, `nano`, `vi`, `vim`, `emacs` | Refused with `Read-only file system`. |

A follower holds the same files as its leader up to its own log end offset, so `ssh` to a follower and `ls -l` shows a lagging replica's shorter segment. A controller's log directory holds only the cluster metadata log, which the terminal does not list: its home is `~`, the disk commands say it is a metadata-only node, and `cat config/controller.properties` prints its configuration.

## Kafka tools

### kafka-topics

| Flag | What it does |
| --- | --- |
| `--list` | Prints the topic names, sorted. |
| `--describe` | Prints each topic's partition count, replication factor and configs, then one line per partition: leader, replicas and in-sync replicas, with the replicas being added or removed during a reassignment, and observers where a topic has them. |
| `--topic <name>` | Limits `--describe` to one topic, and names the topic for `--create`, `--alter` and `--delete`. |
| `--under-replicated-partitions` | Only partitions with fewer in-sync replicas than replicas. |
| `--under-min-isr-partitions` | Only partitions below `min.insync.replicas`. |
| `--at-min-isr-partitions` | Only partitions exactly at `min.insync.replicas`. |
| `--unavailable-partitions` | Only partitions whose leader is missing or down. |
| `--create` | Creates a topic, in free play only, within the same limits as the free-play topic controls. Without `--partitions` or `--replication-factor` it uses the sandbox's defaults. |
| `--partitions <n>` | The partition count for `--create`, or the new, larger count for `--alter`. |
| `--replication-factor <n>` | The replication factor for `--create`, at most the number of brokers. |
| `--config <key=value>` | Topic configs for `--create`, several separated by commas: `retention.ms`, `retention.bytes`, `local.retention.ms`, `cleanup.policy`, `min.insync.replicas` and `remote.storage.enable`. Unless you set `min.insync.replicas`, it equals the replication factor. |
| `--alter` | With `--topic` and `--partitions`, adds partitions. A smaller count fails with `InvalidPartitionsException`. |
| `--delete` | Deletes a topic made with `--create`, in free play only. The sandbox's own topics cannot be deleted. |
| `--if-exists` | With `--describe` or `--delete`, a missing topic is not an error. |
| `--if-not-exists` | With `--create`, an existing topic is not an error. |

When `--under-replicated-partitions`, `--under-min-isr-partitions` or `--unavailable-partitions` finds partitions, the output ends with a `# why?` line that points at the **Why** tab.

### kafka-consumer-groups

| Flag | What it does |
| --- | --- |
| `--list` | Prints the consumer group ids, then any share groups, each marked `(share)`. These are the ids the tools use: a group the canvas labels `cg1` may be `c1` or `g1` here. |
| `--describe --group <id>` | The lag view, one row per partition: `CURRENT-OFFSET` (the committed offset), `LOG-END-OFFSET`, `LAG`, and the owning member's `CONSUMER-ID`, `HOST` and `CLIENT-ID`. A stalled or crashed member shows `-`. |
| `--offsets` | With `--describe`: the same lag table, under its own name. |
| `--state` | With `--describe`: the coordinator, assignment strategy, state and member count. |
| `--members` | With `--describe`: one row per live member with its partition count. `--verbose` adds the assignment. |
| `--all-groups` | Runs `--describe`, `--delete` or `--reset-offsets` on every group. |
| `--reset-offsets` | Prints the new offsets for `--group` or `--all-groups`, on `--topic` or `--all-topics`. Nothing changes without `--execute`. The group must be inactive. |
| `--to-earliest`, `--to-latest` | The two reset targets the simulator carries out. `--to-datetime`, `--by-duration`, `--shift-by`, `--from-file`, `--to-current` and `--to-offset` are accepted and refused. |
| `--execute`, `--dry-run` | `--execute` carries out the reset; `--dry-run`, the default, only shows it. The reset group keeps its settings, including its region on an active-active cluster, and an `auto.offset.reset` of `none` or `latest`; one that is `earliest` or not set comes back as the reset target. |
| `--topic <name>`, `--all-topics` | The topics a reset covers. The simulator resets the whole group, so `--topic` must name a topic the group reads. |
| `--delete` | Deletes the group. A group with live members is refused with `GroupNotEmptyException`. |

### kafka-configs

| Flag | What it does |
| --- | --- |
| `--describe` | With `--entity-type` and `--entity-name`, prints the entity's configs. |
| `--alter` | With `--add-config` or `--delete-config`, changes them. |
| `--entity-type <type>` | `topics`, `users` or `brokers`. Other types answer that the simulator does not model them. |
| `--entity-name <name>` | A topic name; for `users`, a producer id such as `p1`; for `brokers`, a broker number or id. |
| `--add-config <key=value,...>` | Topic keys: `retention.ms`, `retention.bytes`, `local.retention.ms`, `cleanup.policy`, `min.insync.replicas`, `remote.storage.enable` and `unclean.leader.election.enable`. The user key: `producer_byte_rate`. For a retention key, -1 means no limit. Write a list value in brackets: `cleanup.policy=[compact,delete]`. |
| `--delete-config <key,...>` | Resets keys to their defaults. |

A "user" is a producer here, because the producer byte-rate quota is the only quota the simulator enforces; `consumer_byte_rate` answers that it is not modeled. Brokers are describe-only: altering a broker config is refused key by key. An unknown key or a bad value gets an error naming the key, and nothing changes.

### cluster-info

Prints the cluster id, the Kafka version, the control plane with its active controller, epoch and quorum, and a table of brokers with their rack, data center and region where the topology has them. On a two-region topology it first names the region you are in.

### kafka-log-dirs

`--describe` prints, for every broker of the cluster, each partition replica's size, record count and offset lag behind the high watermark. Sizes count 1 KiB per record. `--broker-list` and `--topic-list` are accepted.

### kafka-get-offsets

| Flag | What it does |
| --- | --- |
| `--topic <name>` | The topic to look up. Without it, every topic. |
| `--time <spec>` | `latest` or `-1`, the default, prints the high watermark; `earliest` or `-2` prints the log start offset. Timestamps are not modeled. |
| `--partitions <n,n>` | Only these partitions. |

Each line reads `topic:partition:offset`.

### kafka-reassign-partitions

| Flag | What it does |
| --- | --- |
| `--generate` | Proposes a reassignment and changes nothing. Needs `--topics-to-move-json-file` and `--broker-list`. |
| `--topics-to-move-json-file <json>` | The topics to move, inline: `'{"topics":[{"topic":"orders"}],"version":1}'`. |
| `--broker-list <ids>` | The brokers to spread the topics over, such as `1,2,3,4`. |
| `--disable-rack-aware` | Ignores racks when proposing. |
| `--execute` | Starts the reassignment in `--reassignment-json-file`. |
| `--reassignment-json-file <json>` | The reassignment, inline: `'{"version":1,"partitions":[{"topic":"orders","partition":0,"replicas":[2,3,1]}]}'`. `-` followed by the JSON as the next argument works too. |
| `--reassignment-json <json>`, `--topics-to-move-json <json>` | Other names for the two inline JSON flags. |
| `--verify` | Reports each partition as completed or still in progress, and clears the throttle once all have completed. |
| `--list` | Lists the reassignments in progress. |
| `--cancel` | Returns the partitions in the JSON to the replicas they had before the move. |
| `--throttle <bytes-per-second>` | Accepted and mapped onto the simulator's four replication speeds. It sets the cross-region mirror speed and does not slow the reassignment itself. |

`--generate` always proposes the same placement for the same cluster, where the real tool varies from run to run.

### kafka-leader-election

`--election-type preferred` with `--all-topic-partitions`, or with `--topic <name>` for one topic, moves leadership back to each partition's preferred replica. Exactly one of the two scopes is required. `--partition` is accepted, but the election always covers the whole topic. While the controller quorum is lost, the election changes nothing. `--election-type unclean` explains that the simulator runs unclean elections on its own, when `unclean.leader.election.enable` is set and no in-sync replica is left.

### kafka-server-stop and kafka-server-start

They act on the host you are logged into and take no flags. On a broker, `kafka-server-stop` is a graceful shutdown: the machine stays up, `ssh` still works and `kafka-server-start` brings the broker back. On a controller, stopping takes the machine down with it, so the voter comes back from the Failure Lab rather than from the shell. `kafka-server-start` accepts a properties file path and ignores it.

### kafka-console-producer

`--topic <name>` is required. Each line you type after it becomes a record, until **Ctrl+C** or **Ctrl+D**. It produces as a producer already pinned to that topic, or adds a new producer when there is none. `--property parse.key=true` reads a key from each line, split from the value by `--property key.separator=<sep>`, a tab by default. `--producer-property` is accepted.

### kafka-console-consumer

`--topic <name>` is required. It prints one line per record the group consumes, `topic:partition:offset`, with the key and value when the partition keeps the record. `--group <id>` names the group; without it the tool uses `console-consumer-1` and up. A group that does not exist is created, starting at the earliest offset with `--from-beginning` and at the latest otherwise. On an active-active cluster the new group reads only the copy of the topic in the current host's region. Group ids are shared by every region in the simulator, so a `--group` that another region's cluster already has is refused with the region it belongs to. The tail moves with the timeline, so pausing pauses it. **Ctrl+C** stops it and prints `Processed a total of N messages`.

### kafka-transactions

`list` prints each transactional producer's id, producer and state. `describe --transactional-id <id>` adds the producer epoch and the partitions its open transaction holds. Both also work as `--list` and `--describe`. Unlike the other tools, it reads every region.

### kafka-metadata-quorum

`describe --status` prints the KRaft quorum's leader, epoch, high watermark, maximum follower lag, voters and observers. `describe --replication` prints one row per voter with its log end offset and lag. Fields the simulator does not model print `-`. Both also work as `--describe`. It needs a KRaft quorum with voters.

### kafka-replica-verification

Prints the deprecation notice the real tool logs, then the worst follower lag across the verified partitions, in the current frame. `--topics-include <regex>` chooses the topics, every topic by default; `--topic-white-list` is the older name for it. `--broker-list` is accepted.

## Not supported

`kafka-streams-*`, `kafka-connect-*`, `kafka-features`, `kafka-metadata-shell` and `kafka-storage` print a one-line note that the simulator does not support them. The simulator models the broker surface.