> For the complete documentation index, see [llms.txt](https://docs.warpstream.com/warpstream/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.warpstream.com/warpstream/reference/cli-reference/warpstream-cli.md).

# warpstream cli

The `warpstream cli` subcommand is the command-line tool for interacting with a WarpStream cluster. It provides functionality similar to the Apache Kafka command-line tools for administering, producing to, and consuming from a Kafka cluster.

Usage:

```
warpstream cli <sub-command> [options]
```

Run `warpstream cli` with no sub-command to print the list of available sub-commands, or run `warpstream cli <sub-command> --help` to see the flags a specific sub-command accepts.

{% hint style="info" %}
`warpstream cli-beta` is a deprecated alias for `warpstream cli` and will be removed in a future release. `warpstream cli-old` (and its equivalent `warpstream kcmd`) refers to the previous generation of the CLI; see [warpstream-kcmd.md](/warpstream/reference/cli-reference/warpstream-kcmd.md) for its reference.
{% endhint %}

## Common flags

Every sub-command that talks to a Kafka broker accepts the following flags. They can also be supplied via the corresponding environment variables where noted.

| Flag                       | Environment variable | Description                                                                                             |
| -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------- |
| `-bootstrap-host`          | `BOOTSTRAP_HOST`     | Kafka bootstrap host. Default: `localhost`.                                                             |
| `-bootstrap-port`          | `BOOTSTRAP_PORT`     | Kafka bootstrap port. Default: `9092`.                                                                  |
| `-client-id`               |                      | Client ID to pass along to Kafka. Default: `warpstream-cli`.                                            |
| `-enable-tls`              |                      | Dial with TLS.                                                                                          |
| `-tls-client-cert-file`    |                      | Path to the X.509 client certificate file (PEM).                                                        |
| `-tls-client-key-file`     |                      | Path to the X.509 client private key file (PEM).                                                        |
| `-tls-server-ca-cert-file` |                      | Path to the X.509 server CA certificate file (PEM). If unset, the host's root certificate pool is used. |
| `-sasl-scram`              |                      | Use SASL SCRAM authentication (SASL PLAIN by default).                                                  |
| `-sasl-username`           | `SASL_USERNAME`      | Username for SASL authentication.                                                                       |
| `-sasl-password`           | `SASL_PASSWORD`      | Password for SASL authentication.                                                                       |
| `-kafka-log-level`         |                      | Log level of the underlying Kafka client. One of `DEBUG`, `INFO`, `WARN`, `ERROR`. Default: `WARN`.     |

Sub-commands accept additional flags of their own — see each command's page or run `warpstream cli <sub-command> --help`.

## Sub-commands

### Topic administration

| Sub-command              | Description                                         |
| ------------------------ | --------------------------------------------------- |
| `create-topic`           | Create a new topic.                                 |
| `delete-topics`          | Delete one or more topics.                          |
| `alter-topic-config`     | Change a topic-level configuration value.           |
| `describe-topic-configs` | Print the current configuration values for a topic. |

### Broker & cluster administration

| Sub-command               | Description                                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `alter-broker-config`     | Change a cluster-level (broker) configuration value.                                                         |
| `describe-broker-configs` | Print the current cluster-level (broker) configuration values.                                               |
| `delete-broker-config`    | Delete a cluster-level (broker) configuration entry, which resets that value back to its WarpStream default. |
| `broker-metadata`         | Print broker metadata as returned by the Kafka Metadata API.                                                 |
| `api-versions`            | Print the Kafka API versions supported by the broker.                                                        |

### Consumer groups

| Sub-command                                                                                      | Description                                          |
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| `describe-groups`                                                                                | Print information about one or more consumer groups. |
| [`consumer-group-lag`](/warpstream/reference/cli-reference/warpstream-cli/consumer-group-lag.md) | Print consumer-group lag per partition.              |
| `commit-offsets`                                                                                 | Commit offsets for a consumer group.                 |

### Access control (ACLs)

| Sub-command     | Description                                      |
| --------------- | ------------------------------------------------ |
| `create-acls`   | Create Kafka ACLs.                               |
| `describe-acls` | Print the ACLs currently defined on the cluster. |
| `delete-acls`   | Delete Kafka ACLs.                               |

### Producing & consuming

| Sub-command                                                                                      | Description                                            |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| [`console-producer`](/warpstream/reference/cli-reference/warpstream-cli/console-producer.md)     | Read records from stdin and produce them to a topic.   |
| [`console-consumer`](/warpstream/reference/cli-reference/warpstream-cli/console-consumer.md)     | Consume records from a topic and print them to stdout. |
| [`benchmark-producer`](/warpstream/reference/cli-reference/warpstream-cli/benchmark-producer.md) | Run a producer benchmark against the cluster.          |
| [`benchmark-consumer`](/warpstream/reference/cli-reference/warpstream-cli/benchmark-consumer.md) | Run a consumer benchmark against the cluster.          |

### Diagnostics & tooling

| Sub-command                                                                                | Description                                                                                            |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `diagnose-connection`                                                                      | Diagnose connectivity from this machine to a WarpStream/Kafka cluster.                                 |
| [`diagnose-record`](/warpstream/reference/cli-reference/warpstream-cli/diagnose-record.md) | Print diagnostic information about a specific record at a given topic/partition/offset.                |
| `describe-log-dirs`                                                                        | Print the log-directory information returned by the broker.                                            |
| `certificate-to-dn`                                                                        | Print the distinguished name (DN) that a given X.509 client certificate resolves to.                   |
| [`file-reader`](/warpstream/reference/cli-reference/warpstream-cli/file-reader.md)         | Read a WarpStream Agent segment file directly from object storage and print its contents.              |
| [`file-scrubber`](/warpstream/reference/cli-reference/warpstream-cli/file-scrubber.md)     | Validate the integrity of a WarpStream Agent segment file in object storage.                           |
| `validate-pipeline-config`                                                                 | Validate a managed data pipeline configuration YAML file locally without contacting the control plane. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.warpstream.com/warpstream/reference/cli-reference/warpstream-cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.