kseal

A kubeseal companion CLI for viewing, editing, exporting, encrypting, and offline decrypting Kubernetes Secrets.

Installation

pipx install kseal

uv tool install kseal

pip install kseal

Why kseal?

kubeseal is excellent at one thing: encrypting secrets so they can be safely committed to Git. But day-to-day cluster work involves more than that. For example; inspecting what's inside a sealed secret, swapping secrets across manifests, or recovering secrets without cluster access.

kseal is a DX layer on top of kubeseal that handles the operational side:

If you only ever seal secrets once and push them, kubeseal alone is enough. If you work with sealed secrets daily, kseal saves the repetition.

Requirements

• Python 3.12+
• Kubernetes cluster access (not required for offline decryption)
• Sealed Secrets controller installed in cluster

Quick Start

# View a decrypted secret (requires cluster access)
kseal cat secrets/app.yaml

# Export all secrets to files
kseal export --all

# Encrypt a plaintext secret
kseal encrypt secret.yaml -o sealed.yaml

# Offline decryption (no cluster access needed)
kseal export-keys                              # Backup keys while you have access
kseal decrypt sealed.yaml                      # Decrypt using local keys
kseal edit sealed.yaml                         # Edit decrypted content, then re-encrypt
kseal decrypt-all --in-place                   # Decrypt all SealedSecrets

Commands

kseal cat

View decrypted secret contents with syntax highlighting.

kseal cat path/to/sealed-secret.yaml
kseal cat sealed.yaml --no-color

kseal export

Export decrypted secrets to files.

# Single file
kseal export sealed.yaml
kseal export sealed.yaml -o output.yaml

# All local SealedSecrets
kseal export --all

# All secrets from cluster
kseal export --all --from-cluster

Default output: .unsealed/<original-path> or .unsealed/<namespace>/<name>.yaml

kseal encrypt

Encrypt plaintext secrets using kubeseal.

# To stdout
kseal encrypt secret.yaml

# To file
kseal encrypt secret.yaml -o sealed.yaml

# Replace original file
kseal encrypt secret.yaml --in-place

kseal export-keys

Export sealed-secrets private keys from cluster for offline decryption.

# Export to default location
kseal export-keys                      # → .kseal-keys/

# Custom output directory
kseal export-keys -o ./backup

# From different namespace
kseal export-keys -n kube-system

kseal decrypt

Decrypt a SealedSecret using local private keys (no cluster access needed).

# Using keys from default location
kseal decrypt sealed.yaml

# Using specific key file
kseal decrypt sealed.yaml --private-key ./key.pem

# From stdin
cat sealed.yaml | kseal decrypt

# Filter keys by pattern
kseal decrypt sealed.yaml --private-keys-regex "2025"

kseal decrypt-all

Decrypt all SealedSecrets in a directory using local private keys.

# Search current directory, output to stdout
kseal decrypt-all

# Search specific directory
kseal decrypt-all ./manifests

# Replace files in-place
kseal decrypt-all --in-place

# Custom keys location
kseal decrypt-all --private-keys-path ./backup

kseal edit

Edit a SealedSecret safely: decrypt to a temporary editor file, open $VISUAL or $EDITOR, then re-encrypt the original file only if the plaintext was changed.

kseal edit sealed.yaml
kseal edit sealed.yaml --private-key ./key.pem
kseal edit sealed.yaml --private-keys-regex "2025"

The temporary plaintext file is created with 0600 permissions and removed after the editor exits.

kseal init

Create a configuration file with the latest kubeseal version pinned.

kseal init
kseal init --force  # Overwrite existing

kseal version

Manage kubeseal binary versions.

# List downloaded versions
kseal version list

# Download the latest version
kseal version update

# Set global default version
kseal version set 0.27.0

# Clear default (use highest downloaded)
kseal version set --clear

kseal completion

Generate shell completion scripts.

# Bash
source <(kseal completion bash)

# Zsh
source <(kseal completion zsh)

Add the matching source <(...) line to your shell profile to enable completions permanently.

Configuration

Configuration priority: Environment variables > .kseal-config.yaml > Global settings

# .kseal-config.yaml
version: "0.27.0"
controller_name: sealed-secrets
controller_namespace: kube-system
unsealed_dir: .secrets

# To disable automatic kubeseal version management and use PATH:
# version: disable

Version Management

kseal automatically manages kubeseal binary versions:

• Binaries are stored at ~/.local/share/kseal/kubeseal-<version>
• Each project can pin a specific version in .kseal-config.yaml
• Global settings are stored in ~/.local/share/kseal/settings.yaml
• Set KSEAL_VERSION_DISABLE=1 or version: disable to use kubeseal from PATH

Version resolution order:

1. Disabled management (KSEAL_VERSION_DISABLE=1 or version: disable) uses kubeseal from PATH
2. Project config version (.kseal-config.yaml)
3. Global default version (kseal version set)
4. Highest downloaded version
5. Fetch latest from GitHub (first run only)

Security

• Add .unsealed/ and .kseal-keys/ to your .gitignore
• Never commit plaintext secrets or private keys to version control
• Store exported keys securely (e.g., password manager, encrypted backup)
• Offline decryption with kseal decrypt requires the private keys - keep them safe

Contributing

git clone https://github.com/eznix86/kseal.git
cd kseal
uv sync

# Run tests
make test

# Run linter
make lint

License

MIT