redpanda-data rpk: Install, Profiles & Configuration
rpk is the Redpanda CLI and toolbox — a single binary that manages every
aspect of a Redpanda cluster from the command line. It handles topic management,
cluster operations, security, schema registry, data transforms, cloud
provisioning, and debugging. All commands share a unified configuration model
based on profiles (rpk.yaml) and -X flags that cover the Kafka API,
Admin API, and Schema Registry endpoints.
This is the hub skill. It covers install, config, and command discovery. For depth on individual command groups, see the linked subskills in the Reference Directory below.
Quickstart
1. Install rpk
macOS — Homebrew (recommended)
brew install redpanda-data/tap/redpanda
macOS — Apple Silicon (M1/M2/M3/M4), manual
curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-darwin-arm64.zip \
&& mkdir -p ~/.local/bin \
&& export PATH="$HOME/.local/bin:$PATH" \
&& unzip rpk-darwin-arm64.zip -d ~/.local/bin/
macOS — Intel, manual
curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-darwin-amd64.zip \
&& mkdir -p ~/.local/bin \
&& export PATH="$HOME/.local/bin:$PATH" \
&& unzip rpk-darwin-amd64.zip -d ~/.local/bin/
Linux — amd64
curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-amd64.zip \
&& mkdir -p ~/.local/bin \
&& export PATH="$HOME/.local/bin:$PATH" \
&& unzip rpk-linux-amd64.zip -d ~/.local/bin/
Linux — arm64
curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-arm64.zip \
&& mkdir -p ~/.local/bin \
&& export PATH="$HOME/.local/bin:$PATH" \
&& unzip rpk-linux-arm64.zip -d ~/.local/bin/
Verify:
rpk --version
2. Connect to a self-hosted cluster with a profile
# Create a profile named "local" pointing at localhost
rpk profile create local \
--set brokers=localhost:9092 \
--set admin.hosts=localhost:9644 \
--description "Local dev cluster"
# rpk automatically switches to the new profile.
# Confirm the active profile:
rpk profile current
# Now all commands use "local" without extra flags:
rpk topic list
rpk cluster health
With SASL/SCRAM-256 and TLS:
rpk profile create prod \
--set brokers=broker1.example.com:9092,broker2.example.com:9092 \
--set admin.hosts=broker1.example.com:9644,broker2.example.com:9644 \
--set tls.enabled=true \
--set sasl.mechanism=SCRAM-SHA-256 \
--set user=alice \
--set pass=s3cr3t \
--description "Production cluster"
3. Connect to a Redpanda Cloud cluster
# Log in (opens browser for SSO)
rpk cloud login
# Create a profile from a Cloud cluster ID or name
rpk profile create --from-cloud <cluster-id-or-name>
# Or interactively pick a cluster:
rpk profile create --from-cloud
# The profile is now active and contains the broker/registry/admin URLs
# pulled from the Cloud control plane:
rpk topic list
4. One-off override with -X (no profile change)
# Override brokers for a single command
rpk topic list -X brokers=myhost:9092
# SASL in one shot
rpk topic consume orders \
-X brokers=myhost:9092 \
-X tls.enabled=true \
-X sasl.mechanism=SCRAM-SHA-256 \
-X user=alice \
-X pass=s3cr3t
# See all available -X keys
rpk -X list
# See detailed description of each -X key
rpk -X help
5. Switch between profiles
rpk profile list # list all profiles
rpk profile current # show active profile
rpk profile use prod # switch to "prod"
rpk profile use local # switch back to "local"
# Temporary override without switching:
rpk topic list --profile prod
# or via env var:
RPK_PROFILE=prod rpk topic list
Configuration model
rpk resolves configuration in priority order (highest wins):
- -X flags on the command line (current command only)
- RPK_ environment variables* (current shell session)
- rpk profile in
rpk.yaml(persistent, recommended) redpanda.yamlrpk section (system-wide defaults, self-managed only)
rpk.yaml location
- Linux:
~/.config/rpk/rpk.yaml - macOS:
~/Library/Application Support/rpk/rpk.yaml
All profiles live in the same file. The globals section applies to all
profiles (timeouts, prompt format, etc.).
-X flag → RPK_ env var conversion
Every -X key=value becomes RPK_KEY=value by uppercasing and replacing .
with _. Examples:
-X option |
Environment variable |
|---|---|
brokers |
RPK_BROKERS |
tls.enabled |
RPK_TLS_ENABLED |
tls.ca |
RPK_TLS_CA |
sasl.mechanism |
RPK_SASL_MECHANISM |
user |
RPK_USER |
pass |
RPK_PASS |
admin.hosts |
RPK_ADMIN_HOSTS |
registry.hosts |
RPK_REGISTRY_HOSTS |
cloud.client_id |
RPK_CLOUD_CLIENT_ID |
cloud.client_secret |
RPK_CLOUD_CLIENT_SECRET |
Profile selection: RPK_PROFILE=<name>
Command groups at a glance
| Command group | What it does | Subskill |
|---|---|---|
rpk topic |
Create, describe, alter, delete topics; produce and consume records | rpk-topic |
rpk cluster |
Cluster health/metadata, config, partitions, maintenance, connections, quotas, self-test | rpk-cluster |
rpk group |
Consumer group list/describe/seek/delete | rpk-group |
rpk security |
SASL users, Kafka ACLs, RBAC roles, secrets | rpk-security |
rpk cloud |
Log in to Cloud, create profiles, BYOC provisioning | rpk-cloud |
rpk debug |
Collect debug bundles (local and remote), local process info | rpk-debug |
rpk registry |
Schema Registry subjects, schemas, compatibility, modes | rpk-registry |
rpk transform |
Build and deploy Wasm data transforms | rpk-transform |
rpk ai |
AI/MCP integration — MCP server for LLM agents | ai |
rpk connect |
Run Redpanda Connect (formerly Benthos) pipelines | connect |
rpk profile |
Manage rpk profiles (create/use/list/edit/set/delete) | this skill |
rpk acl |
Deprecated — use rpk security acl instead |
rpk-security |
rpk generate |
Generate completions, app scaffolding, prometheus config | — |
rpk version |
Print rpk version | — |
rpk container |
Manage local Redpanda containers for dev | — |
rpk plugin |
Manage rpk plugins | — |
rpk redpanda |
Operate the local broker: start/stop, mode, tune, check, node config, admin (brokers decommission) — self-managed only | rpk-redpanda |
rpk iotune |
Benchmark disk I/O and write optimal io properties (Linux-only) | rpk-redpanda |
rpk oxla |
Redpanda Oxla SQL engine — "Coming Soon" CLI stub | sql skills |
rpk shadow |
Manage Redpanda Shadow Links (create/describe/update/delete/list/failover) | — |
Enterprise features and the license
Redpanda's key differentiators are Enterprise Edition features. They require a
valid Enterprise license — new clusters (v24.3+) automatically get a 30-day trial
license on first start. Most are enabled/configured through rpk cluster config
(cluster-wide keys) or rpk topic create -c / rpk topic alter-config --set
(topic properties); a few have dedicated command groups (rpk shadow,
rpk security role, rpk cluster license).
# Check license + whether you are in violation (enterprise features without a license)
rpk cluster license info # alias: status; supports --format json
rpk cluster license set --path /etc/redpanda/redpanda.license
rpk generate license --apply # generate + apply a 30-day trial
Enterprise features operated via rpk, with their primary control:
| Feature | rpk control (primary key/command) |
|---|---|
| Tiered Storage | cloud_storage_enabled; topic redpanda.remote.read/write/delete, retention.local.target.ms/bytes |
| Cloud Topics | cloud_topics_enabled; topic redpanda.storage.mode=cloud |
| Iceberg Topics | iceberg_enabled; topic redpanda.iceberg.mode (+ .target.lag.ms, .partition.spec, .invalid.record.action, .delete) |
| Continuous Data Balancing | partition_autobalancing_mode=continuous (+ partition_autobalancing_*, core_balancing_continuous) |
| Shadow Linking / DR | rpk shadow create/status/update/failover/delete, rpk shadow config generate |
| Remote Read Replicas | cloud_storage_enable_remote_read; topic redpanda.remote.readreplica=<bucket> |
| Leadership Pinning | topic redpanda.leaders.preference; cluster default_leaders_preference |
| Audit Logging | audit_enabled (+ audit_* keys) |
| RBAC / GBAC | rpk security role ...; rpk security acl create --allow-principal Group:... |
| OIDC / Kerberos auth | cluster sasl_mechanisms (OAUTHBEARER/GSSAPI), http_authentication |
| Schema ID Validation | enable_schema_id_validation; topic redpanda.{key,value}.schema.id.validation |
| FIPS | node fips_mode (rpk redpanda config set redpanda.fips_mode enabled) |
Full nested config keys, topic properties, accepted values, and the disable-to-exit-violation commands for each feature are in enterprise-features.md.
Reference Directory
- install.md: Installing rpk on macOS (Homebrew and manual), Linux (amd64/arm64), verifying the install, and keeping rpk up to date.
- profiles.md: Full rpk profile reference — rpk.yaml location, profile create/use/list/current/edit/set/delete/rename, --from-cloud, RPK_PROFILE env var, and the profile data structure.
- x-flags-and-config.md: Every -X option with type, default, and example; RPK_* env var mapping; configuration priority; globals settings; and rpk.yaml vs redpanda.yaml.
- command-map.md: One-line description of every top-level rpk command group with a pointer to the dedicated subskill for each.
- enterprise-features.md: Redpanda Enterprise differentiators operated through rpk — license management (
rpk cluster license), Tiered Storage, Cloud Topics, Iceberg Topics, Continuous Data Balancing, Shadow Linking/DR (rpk shadow), Remote Read Replicas, Audit Logging, RBAC, OIDC/Kerberos/FIPS auth, Schema ID Validation, and Leadership Pinning — with their nested cluster-config keys, topic properties, accepted values, and disable-to-exit-violation commands. All require an Enterprise license.