# rpk -X

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [streaming-full.txt](https://docs.redpanda.com/streaming-full.txt)

---
title: rpk -X
latest-redpanda-tag: v25.2.1
latest-console-tag: v3.7.3
latest-operator-version: v26.1.4
# EOL = End-of-Life (support lifecycle status)
page-is-nearing-eol: "true"
page-is-past-eol: "false"
page-eol-date: July 31, 2026
latest-connect-version: 4.93.0
docname: rpk/rpk-x-options
page-component-name: streaming
page-version: "25.2"
page-component-version: "25.2"
page-component-title: Streaming
page-relative-src-path: rpk/rpk-x-options.adoc
page-edit-url: https://github.com/redpanda-data/docs/edit/v/25.2/modules/reference/pages/rpk/rpk-x-options.adoc
description: This command lets you override <code>rpk</code> configuration options.
page-git-created-date: "2023-08-04"
page-git-modified-date: "2025-08-21"
support-status: nearing end-of-life
---

<!-- Source: https://docs.redpanda.com/streaming/25.2/reference/rpk/rpk-x-options.md -->

Use `rpk -X` flag to override any rpk-specific configuration option.

Every configuration flag for `rpk` is a `key=value` option following the `-X` flag. For example, `rpk -X tls.enabled=true` enables TLS for the Kafka API.

Every `-X` option can be translated into an environment variable by prefixing with `RPK_` and replacing periods (`.`) with underscores (`_`). For example, the flag `tls.enabled` has the equivalent environment variable `RPK_TLS_ENABLED`.

> ❗ **IMPORTANT**
>
> -   Flags common across all `rpk` commands in previous versions (for example, `--brokers`, `--tls-enabled`) are deprecated.
>
> -   Functionality of all deprecated flags are supported as `-X` options.

> 💡 **TIP**
>
> -   For persistent configuration across commands and sessions, Redpanda Data recommends using [rpk profiles](https://docs.redpanda.com/streaming/25.2/get-started/config-rpk-profile/) instead of environment variables or `-X` flags.
>
> -   `rpk` supports command-line (tab) completion for `-X` flag keys.
>
> -   Each `rpk` command’s `-help` text prints information specific to the command. To view a description of `-X` options, run `rpk -X list` to list supported options, or run `rpk -X help` to get details about supported options.

## [](#configuration-priority)Configuration priority

`rpk` resolves configuration values in the following priority order where higher priority options override lower priority ones:

1.  **Command-line flags** (including `-X` options): Applies to current command only

2.  **Environment variables**: `RPK_*` environment variables lasts for shell session

3.  **rpk profile** (`rpk.yaml`): Persistent across sessions (recommended)

4.  **Redpanda configuration** (`redpanda.yaml` rpk section): System-wide defaults


## [](#environment-variables)Environment variables

### [](#rpk-environment-variables)RPK_\* environment variables

Every `-X` option has a corresponding `RPK_*` environment variable. Convert by prefixing with `RPK_` and replacing dots with underscores:

| -X Option | Environment Variable |
| --- | --- |
| brokers | RPK_BROKERS |
| tls.enabled | RPK_TLS_ENABLED |
| tls.insecure_skip_verify | RPK_TLS_INSECURE_SKIP_VERIFY |
| tls.ca | RPK_TLS_CA |
| tls.cert | RPK_TLS_CERT |
| tls.key | RPK_TLS_KEY |
| sasl.mechanism | RPK_SASL_MECHANISM |
| user | RPK_USER |
| pass | RPK_PASS |
| admin.hosts | RPK_ADMIN_HOSTS |
| admin.tls.enabled | RPK_ADMIN_TLS_ENABLED |
| admin.tls.insecure_skip_verify | RPK_ADMIN_TLS_INSECURE_SKIP_VERIFY |
| admin.tls.ca | RPK_ADMIN_TLS_CA |
| admin.tls.cert | RPK_ADMIN_TLS_CERT |
| admin.tls.key | RPK_ADMIN_TLS_KEY |
| registry.hosts | RPK_REGISTRY_HOSTS |
| registry.tls.enabled | RPK_REGISTRY_TLS_ENABLED |
| registry.tls.insecure_skip_verify | RPK_REGISTRY_TLS_INSECURE_SKIP_VERIFY |
| registry.tls.ca | RPK_REGISTRY_TLS_CA |
| registry.tls.cert | RPK_REGISTRY_TLS_CERT |
| registry.tls.key | RPK_REGISTRY_TLS_KEY |
| cloud.client_id | RPK_CLOUD_CLIENT_ID |
| cloud.client_secret | RPK_CLOUD_CLIENT_SECRET |
| globals.prompt | RPK_GLOBALS_PROMPT |
| globals.no_default_cluster | RPK_GLOBALS_NO_DEFAULT_CLUSTER |
| globals.command_timeout | RPK_GLOBALS_COMMAND_TIMEOUT |
| globals.dial_timeout | RPK_GLOBALS_DIAL_TIMEOUT |
| globals.request_timeout_overhead | RPK_GLOBALS_REQUEST_TIMEOUT_OVERHEAD |
| globals.retry_timeout | RPK_GLOBALS_RETRY_TIMEOUT |
| globals.fetch_max_wait | RPK_GLOBALS_FETCH_MAX_WAIT |
| globals.kafka_protocol_request_client_id | RPK_GLOBALS_KAFKA_PROTOCOL_REQUEST_CLIENT_ID |

## [](#duration-format)Duration format

Duration values use Go’s standard duration format. A duration string is a sequence of decimal numbers with unit suffixes:

-   `ns` = nanoseconds

-   `us` or `µs` = microseconds

-   `ms` = milliseconds

-   `s` = seconds

-   `m` = minutes

-   `h` = hours


**Examples**: `30s`, `1m30s`, `2h`, `500ms`, `1h15m30s`

You can combine multiple units: `2h45m30s` means 2 hours, 45 minutes, and 30 seconds.

## [](#configuration-examples)Configuration examples

To persist configuration across sessions, use a [rpk profile](https://docs.redpanda.com/streaming/25.2/get-started/config-rpk-profile/):

Create a profile:

```bash
rpk profile create <profile-name> \
  --set brokers=<broker1:port>,<broker2:port> \
  --set user=<username> \
  --set pass=<password> \
  --set sasl.mechanism=<mechanism> \
  --set tls.enabled=true \
  --description "<profile-description>"
```

Use the profile for commands:

```bash
rpk topic list --profile <profile-name>
```

For temporary use or automation scripts, set environment variables:

```bash
export RPK_BROKERS="<broker1:port>,<broker2:port>"
export RPK_USER="<username>"
export RPK_PASS="<password>"
export RPK_SASL_MECHANISM="<mechanism>"
export RPK_TLS_ENABLED="true"
```

## [](#options)Options

The following options are available:

### [](#brokers)brokers

A comma-delimited list of broker `host:port` pairs to connect to the Kafka API.

**Type**: string

**Default**: `localhost:9092`

**Example**: `brokers=127.0.0.1:9092,localhost:9094`

**Usage**:

```none
rpk topic list -X brokers=<host:port>,<host:port>
```

* * *

### [](#tls-enabled)tls.enabled

A boolean that enables `rpk` to speak TLS to your broker’s Kafka API listeners.

You can use this if you have well known certificates set up on your Kafka API. If you use mTLS, specifying mTLS certificate filepaths automatically opts into `tls.enabled`.

**Type**: boolean

**Default**: `false`

**Example**: `tls.enabled=true`

**Usage**:

```none
rpk topic list -X tls.enabled=<value>
```

* * *

### [](#tls-insecure_skip_verify)tls.insecure_skip_verify

A boolean that disables `rpk` from verifying the broker’s certificate chain.

**Type**: boolean

**Default**: `false`

**Example**: `tls.insecure_skip_verify=true`

**Usage**:

```none
rpk topic list -X tls.insecure_skip_verify=<value>
```

* * *

### [](#tls-ca)tls.ca

A filepath to a PEM-encoded CA certificate file to talk to your broker’s Kafka API listeners with mTLS.

You may need this option if your listeners are using a certificate by a well known authority that is not bundled with your operating system.

**Type**: string

**Default**: ""

**Example**: `tls.ca=/path/to/ca.pem`

**Usage**:

```none
rpk topic list -X tls.ca=<filepath>
```

* * *

### [](#tls-cert)tls.cert

A filepath to a PEM-encoded client certificate file to talk to your broker’s Kafka API listeners with mTLS.

**Type**: string

**Default**: ""

**Example**: `tls.cert=/path/to/cert.pem`

**Usage**:

```none
rpk topic list -X tls.cert=<filepath>
```

* * *

### [](#tls-key)tls.key

A filepath to a PEM-encoded client key file to talk to your broker’s Kafka API listeners with mTLS.

**Type**: string

**Default**: ""

**Example**: `tls.key=/path/to/key.pem`

**Usage**:

```none
rpk topic list -X tls.key=<filepath>
```

* * *

### [](#sasl-mechanism)sasl.mechanism

The SASL mechanism to use for authentication.

**Type**: string

**Default**: ""

**Acceptable values**: `SCRAM-SHA-256`, `SCRAM-SHA-512`, `PLAIN`

> 📝 **NOTE**
>
> With Redpanda, the Admin API can be configured to require basic authentication with your Kafka API SASL credentials. This defaults to `SCRAM-SHA-256` if no mechanism is specified.

**Example**: `sasl.mechanism=SCRAM-SHA-256`

**Usage**:

```none
rpk topic list -X sasl.mechanism=<mechanism>
```

* * *

### [](#user)user

The SASL username to use for authentication. It’s also used for the Admin API if you have configured it to require basic authentication.

**Type**: string

**Default**: ""

**Example**: `user=myusername`

**Usage**:

```none
rpk topic list -X user=<username>
```

* * *

### [](#pass)pass

The SASL password to use for authentication. It’s also used for the Admin API if you have configured it to require basic authentication.

**Type**: string

**Default**: ""

**Example**: `pass=mypassword`

**Usage**:

```none
rpk topic list -X pass=<password>
```

* * *

### [](#admin-hosts)admin.hosts

A comma-delimited list of admin hosts to connect to.

**Type**: string

**Default**: `localhost:9644`

**Example**: `admin.hosts=192.168.1.1:9644,192.168.1.2:9644`

* * *

### [](#admin-tls-enabled)admin.tls.enabled

A boolean that enables `rpk` to speak TLS to your broker’s Admin API listeners.

You can use this if you have well known certificates set up on your Admin API. If you use mTLS, specifying mTLS certificate filepaths automatically opts into `admin.tls.enabled`.

**Type**: boolean

**Default**: `false`

**Example**: `admin.tls.enabled=true`

**Usage**:

```none
rpk cluster info -X admin.tls.enabled=<value>
```

* * *

### [](#admin-tls-insecure_skip_verify)admin.tls.insecure_skip_verify

A boolean that disables `rpk` from verifying the broker’s certificate chain.

**Type**: boolean

**Default**: `false`

**Example**: `admin.tls.insecure_skip_verify=true`

**Usage**:

```none
rpk cluster info -X admin.tls.insecure_skip_verify=<value>
```

* * *

### [](#admin-tls-ca)admin.tls.ca

A filepath to a PEM-encoded CA certificate file to talk to your broker’s Admin API listeners with mTLS. You may also need this if your listeners are using a certificate by a well known authority that is not yet bundled with your operating system.

**Type**: string

**Default**: ""

**Example**: `admin.tls.ca=/path/to/ca.pem`

**Usage**:

```none
rpk cluster info -X admin.tls.ca=<filepath>
```

* * *

### [](#admin-tls-cert)admin.tls.cert

A filepath to a PEM-encoded client certificate file to talk to your broker’s Admin API listeners with mTLS.

**Type**: string

**Default**: ""

**Example**: `admin.tls.cert=/path/to/cert.pem`

**Usage**:

```none
rpk cluster info -X admin.tls.cert=<filepath>
```

* * *

### [](#admin-tls-key)admin.tls.key

A filepath to a PEM-encoded client key file to talk to your broker’s Admin API listeners with mTLS.

**Type**: string

**Default**: ""

**Example**: `admin.tls.key=/path/to/key.pem`

**Usage**:

```none
rpk cluster info -X admin.tls.key=<filepath>
```

* * *

### [](#registry-hosts)registry.hosts

A comma-delimited list of Schema Registry hosts to connect to.

**Type**: string

**Default**: `localhost:8081`

**Example**: `registry.hosts=192.168.1.1:8081,192.168.1.2:8081`

**Usage**:

```none
rpk registry schema list -X registry.hosts=<host:port>,<host:port>
```

* * *

### [](#registry-tls-enabled)registry.tls.enabled

A boolean that enables `rpk` to use TLS with your broker’s Schema Registry API listeners.

You can use this if you have well known certificates set up on your Schema Registry API. If you use mTLS, specifying mTLS certificate filepaths automatically opts into `registry.tls.enabled`.

**Type**: boolean

**Default**: `false`

**Example**: `registry.tls.enabled=true`

**Usage**:

```none
rpk registry schema list -X registry.tls.enabled=<value>
```

* * *

### [](#registry-tls-insecure_skip_verify)registry.tls.insecure_skip_verify

A boolean that disables `rpk` from verifying the broker’s certificate chain.

**Type**: boolean

**Default**: `false`

**Example**: `registry.tls.insecure_skip_verify=true`

**Usage**:

```none
rpk registry schema list -X registry.tls.insecure_skip_verify=<value>
```

* * *

### [](#registry-tls-ca)registry.tls.ca

A filepath to a PEM-encoded CA certificate file to talk to your broker’s Schema Registry API listeners with mTLS.

**Type**: string

**Default**: ""

**Example**: `registry.tls.ca=/path/to/ca.pem`

**Usage**:

```none
rpk registry schema list -X registry.tls.ca=<filepath>
```

* * *

### [](#registry-tls-cert)registry.tls.cert

A filepath to a PEM-encoded client certificate file to talk to your broker’s Schema Registry API listeners with mTLS.

**Type**: string

**Default**: ""

**Example**: `registry.tls.cert=/path/to/cert.pem`

**Usage**:

```none
rpk registry schema list -X registry.tls.cert=<filepath>
```

* * *

### [](#registry-tls-key)registry.tls.key

A filepath to a PEM-encoded client key file to talk to your broker’s Schema Registry API listeners with mTLS.

**Type**: string

**Default**: ""

**Example**: `registry.tls.key=/path/to/key.pem`

**Usage**:

```none
rpk registry schema list -X registry.tls.key=<filepath>
```

* * *

### [](#cloud-client_id)cloud.client_id

An OAuth client ID to use for authenticating with the Redpanda Cloud API.

**Type**: string

**Default**: ""

**Example**: `cloud.client_id=abcdef123456`

**Usage**:

```none
rpk cloud cluster list -X cloud.client_id=<client-id>
```

* * *

### [](#cloud-client_secret)cloud.client_secret

An OAuth client secret to use for authenticating with the Redpanda Cloud API.

**Type**: string

**Default**: ""

**Example**: `cloud.client_secret=secretvalue789`

**Usage**:

```none
rpk cloud cluster list -X cloud.client_secret=<client-secret>
```

* * *

### [](#globals-prompt)globals.prompt

A format string to use for the default prompt. See [`rpk profile prompt`](https://docs.redpanda.com/streaming/25.2/reference/rpk/rpk-profile/rpk-profile-prompt/) for more information.

**Type**: string

**Default**: `bg-red "%n"`

**Example**: `globals.prompt="%n"`

**Usage**:

```none
rpk profile edit -X globals.prompt=<format-string>
```

* * *

### [](#globals-no_default_cluster)globals.no_default_cluster

A boolean that disables `rpk` from communicating to `localhost:9092` if no other cluster is specified.

**Type**: boolean

**Default**: `false`

**Example**: `globals.no_default_cluster=true`

**Usage**:

```none
rpk topic list -X globals.no_default_cluster=<value>
```

* * *

### [](#globals-command_timeout)globals.command_timeout

Sets a timeout for all commands issued through rpk.

**Type**: [duration](#duration-format)

**Default**: `30s`

**Example**: `globals.command_timeout=30s`

* * *

### [](#globals-dial_timeout)globals.dial_timeout

A duration that `rpk` will wait for a connection to be established before timing out.

**Type**: [duration](#duration-format)

**Default**: `3s`

**Example**: `globals.dial_timeout=3s`

**Usage**:

```none
rpk topic list -X globals.dial_timeout=<duration>
```

* * *

### [](#globals-request_timeout_overhead)globals.request_timeout_overhead

A duration that limits how long `rpk` waits for responses.

**Type**: [duration](#duration-format)

**Default**: `10s`

> 📝 **NOTE**
>
> `globals.request_timeout_overhead` applies in addition to any request-internal timeout.
>
> For example, `ListOffsets` has no `Timeout` field, so `rpk` will wait `request_timeout_overhead` for a response. However, `JoinGroup` has a `RebalanceTimeoutMillis` field, so `request_timeout_overhead` is applied on top of the rebalance timeout.

**Example**: `globals.request_timeout_overhead=5s`

**Usage**:

```none
rpk topic list -X globals.request_timeout_overhead=<duration>
```

* * *

### [](#globals-retry_timeout)globals.retry_timeout

This timeout specifies how long `rpk` will retry Kafka API requests.

**Type**: [duration](#duration-format)

**Default**: `30s`

This timeout is evaluated before any backoff:

-   If a request fails, `rpk` first checks if the retry timeout has elapsed.

    -   If the retry timeout has elapsed, `rpk` stops retrying.

    -   Otherwise, `rpk` waits for the backoff and then retries.



**Example**: `globals.retry_timeout=11s`

**Usage**:

```none
rpk topic list -X globals.retry_timeout=<duration>
```

* * *

### [](#globals-fetch_max_wait)globals.fetch_max_wait

This timeout specifies the maximum duration that brokers will wait before replying to a fetch request with available data.

**Type**: [duration](#duration-format)

**Default**: `5s`

**Example**: `globals.fetch_max_wait=5s`

**Usage**:

```none
rpk topic consume my-topic -X globals.fetch_max_wait=<duration>
```

* * *

### [](#globals-kafka_protocol_request_client_id)globals.kafka_protocol_request_client_id

This string value is the client ID that `rpk` uses when issuing Kafka protocol requests to Redpanda. This client ID shows up in Redpanda logs and metrics. Changing it can be useful if you want to have your own `rpk` client stand out from others that are also interacting with the cluster.

**Type**: string

**Default**: `rpk`

**Example**: `globals.kafka_protocol_request_client_id=my-rpk-client`

**Usage**:

```none
rpk topic list -X globals.kafka_protocol_request_client_id=<client-id>
```