Streaming

rpk -X

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.

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

  • For persistent configuration across commands and sessions, Redpanda Data recommends using rpk profiles 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

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

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

To persist configuration across sessions, use a rpk profile:

Create a profile:

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:

rpk topic list --profile <profile-name>

For temporary use or automation scripts, set environment variables:

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

The following options are available:

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

sasl.mechanism

The SASL mechanism to use for authentication.

Type: string

Default: ""

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

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:

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

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:

rpk topic list -X user=<username>

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:

rpk topic list -X pass=<password>

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

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:

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

globals.prompt

A format string to use for the default prompt. See rpk profile prompt for more information.

Type: string

Default: bg-red "%n"

Example: globals.prompt="%n"

Usage:

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

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:

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

globals.command_timeout

Sets a timeout for all commands issued through rpk.

Type: duration

Default: 30s

Example: globals.command_timeout=30s

globals.dial_timeout

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

Type: duration

Default: 3s

Example: globals.dial_timeout=3s

Usage:

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

globals.request_timeout_overhead

A duration that limits how long rpk waits for responses.

Type: duration

Default: 10s

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:

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

globals.retry_timeout

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

Type: duration

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:

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

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

Default: 5s

Example: globals.fetch_max_wait=5s

Usage:

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

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:

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