kseal 2.1.1

A kubeseal companion CLI - decrypt, edit, export, and encrypt Kubernetes Secrets with automatic binary management

kseal

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

Installation

pipx install kseal

Other installation methods

With uv:

uv tool install kseal

With pip:

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:

	kubeseal	kseal
Encrypt secrets for GitOps	✅	✅ (via kubeseal)
View / inspect sealed secrets	❌	✅ kseal cat
Edit sealed secrets in-place	❌	✅ kseal edit
Offline decryption	❌	✅ kseal decrypt
Export secrets to files	❌	✅ kseal export
Per-project config (no repeated flags)	❌	✅ .kseal-config.yaml
In-place secret swapping in manifests	❌	✅ kseal encrypt --in-place

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

Option	Environment Variable	Default
version	KSEAL_VERSION	Global default or highest downloaded
version: disable	KSEAL_VERSION_DISABLE=1	Use kubeseal from PATH without version checks or downloads
controller_name	KSEAL_CONTROLLER_NAME	sealed-secrets
controller_namespace	KSEAL_CONTROLLER_NAMESPACE	sealed-secrets
unsealed_dir	KSEAL_UNSEALED_DIR	.unsealed

Example config file

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