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 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.