Home

Keyseal

Keyseal is a CLI tool for managing encrypted secrets in Git repositories. It provides a workflow layer over SOPS and age, giving you logical names, structured validation, multi-format rendering, and health checks - without replacing the underlying encryption.

If you already use SOPS directly, Keyseal adds:

• A naming convention that maps production/platform/app to production/platform/app.enc.yaml
• Structured secret documents with validation (kind: env, required fields, key format rules)
• render - decrypt one or more secrets and write a merged dotenv/JSON/YAML file in one step
• exec - inject secrets as environment variables into a subprocess without writing files
• doctor - pre-flight checks that catch placeholder recipients, plaintext files at encrypted paths, SOPS misconfiguration, and more

What it is not

Keyseal is not a secret server. It does not manage access, audit logs, dynamic credentials, or secret rotation. It does not implement any encryption itself - all cryptographic operations are delegated to the SOPS binary. It is not a replacement for Vault, AWS Secrets Manager, or similar systems.

It is a structured, opinionated workflow for teams that keep encrypted secrets in Git and need something more reliable than raw SOPS invocations.

How it fits

Git repo  →  keyseal.yaml  →  Keyseal (workflow)  →  SOPS (encryption)  →  age keys
                                    ↓
                            .enc.yaml files (ciphertext in repo)
                                    ↓
                            keyseal render / keyseal exec
                                    ↓
                          dotenv / JSON / YAML / subprocess env

Your encrypted files live in the repository. Keyseal knows how to find them (by logical name), how to validate their structure (via schema), and how to produce usable output from them. SOPS handles the actual encrypt/decrypt.

Current status

The project is under active development and not yet suitable for production use. The core workflow is functional and the schema is stable at version 1. The profiles configuration section is parsed and validated but not yet executed by any command. Only kind: env is supported.

Navigation

Where to start
Installation	Prerequisites, build from source, release binaries
Quick Start	End-to-end example from init to render
Concepts	Mental model, how the pieces fit

Reference
Configuration Reference	keyseal.yaml field-by-field
Command Reference	Every command, every flag
Secret File Format	Document schema, validation rules
Repository Layout	Expected directory structure

Operations
Doctor	Health checks: what they test and how to fix failures
Templates	Built-in starter templates
Troubleshooting	Common problems and fixes
Security Notes	What Keyseal protects (and does not protect)

Development
Build and Release	Makefile, cross-platform dist, release workflow
Contributing	Project layout, tests, how to contribute
FAQ	Common questions