Keyseal

Default flow: keyseal add scaffolds and encrypts a new secret document immediately, without writing plaintext starter content to the final .enc.yaml path.

Keyseal is a small Go CLI that standardizes encrypted file workflows around sops, age, and Git. It was built to solve a real production problem: managing Git-backed SOPS secret workflows at scale.

It helps teams:

• keep encrypted secret files in a repository
• scaffold new secret documents
• open encrypted files in sops
• inspect Git status, diffs, and file history by logical name
• commit and roll back Keyseal-managed changes without staging the whole repo
• render decrypted values into runtime formats
• run commands with decrypted environment variables injected
• validate repository layout and config health
• enforce strict CI verification before release or deployment

Keyseal does not implement encryption itself, replace SOPS, run a server, expose an API, or behave like a hosted secrets platform.

Keyseal uses the official SOPS Go decrypt library for read-only decryption in render, exec, and validation paths. The external SOPS binary is still required for commands that create, edit, or rotate encrypted files.

Why it exists

SOPS already solves encryption and editing well. Keyseal stays one layer above that and makes a repo-backed workflow more predictable:

• consistent file naming and layout
• Git-aware workflows around the encrypted files that already live in the repo
• small config with strong defaults
• repeatable render and exec flows
• clear validation for common mistakes

Requirements

• Go 1.25+ to build the CLI
• age recipients configured in .sops.yaml

Developer/admin machines that run keyseal add, keyseal edit, or keyseal updatekeys also need the external sops binary.

Production, CI, or deploy machines that only run keyseal render, keyseal exec, keyseal doctor, or keyseal verify need only:

• the keyseal binary
• the encrypted secrets files/repo
• age private key material, usually through SOPS_AGE_KEY_FILE or sops.age_key_file

They do not need the external sops binary or the external age binary. Servers need the age key, not the age CLI.

Installation

Pre-built binaries and Linux packages are available on the GitHub Releases page. Each release includes tar.gz archives (Linux and macOS, amd64 and arm64), .deb and .rpm packages (Linux amd64 and arm64), and SHA256 checksums.

Linux (Debian/Ubuntu):

sudo dpkg -i keyseal_<version>_amd64.deb

Linux (RHEL/Fedora/SUSE):

sudo rpm -i keyseal-<version>-1.x86_64.rpm

Other platforms: extract the binary from the appropriate tar.gz archive and place it somewhere in your PATH.

Quick start

make build
./bin/keyseal init
./bin/keyseal add production/platform/app --template laravel
./bin/keyseal edit production/platform/app
./bin/keyseal status
./bin/keyseal commit -m "Add production app secret"
./bin/keyseal render production/platform/app --stdout
./bin/keyseal doctor

For a fuller walkthrough, see the Quick Start guide and the wiki.

Build

make tidy
make check
make build
./bin/keyseal --version
./bin/keyseal --help

Command overview

• keyseal init bootstraps a repository layout, keyseal.yaml, and .sops.yaml
• keyseal add <logical-name> creates and encrypts a starter env secret document, with optional immediate Git commit support
• keyseal edit <logical-name> opens the target file with sops, bootstrapping empty placeholder files first when needed
• keyseal updatekeys [logical-name...] syncs SOPS recipients from .sops.yaml, with optional explicit Git commit support
• keyseal status [logical-name] shows Git status for Keyseal-managed files
• keyseal diff <logical-name> shows git diff for one secret file
• keyseal history <logical-name> shows file-scoped Git history for one secret file
• keyseal commit stages current Keyseal-managed changes and creates a Git commit
• keyseal rollback <logical-name> --to <commit> restores one secret file from Git history
• keyseal render <logical-name...> decrypts, merges, and renders secret values, skipping empty placeholder files
• keyseal exec <logical-name...> -- <command...> runs a child process with merged env vars
• keyseal doctor validates config sanity, SOPS CLI availability, age key/deployment context, .sops.yaml readiness, and common mistakes
• keyseal verify runs strict CI checks and fails on any doctor warning or failure
• keyseal version reports version, commit, and build date metadata

Detailed flags, examples, and behavior notes live in the Command Reference and wiki.

What Keyseal is not

• not a crypto implementation
• not a Vault replacement
• not a secret hosting service
• not a daemon or web UI
• not a Kubernetes controller

Usage

keyseal add production/platform/app --template laravel
keyseal edit production/platform/app
keyseal updatekeys production/platform/app --yes
keyseal status production/platform/app
keyseal history production/platform/app --oneline
keyseal commit -m "Update production app secret"
keyseal render production/platform/app --stdout --format json
keyseal exec production/platform/app -- php artisan migrate
keyseal rollback production/platform/app --to <commit> --dry-run
keyseal doctor
keyseal verify

Key workflow details:

• -m, --message implies commit on mutating commands
• git.auto_commit is off by default
• sops.age_key_file is used as the default age key path unless SOPS_AGE_KEY_FILE is already set
• read-only decrypt paths use the SOPS Go library and do not require external sops or age binaries
• mutating commands check the configured sops.binary before creating, editing, or rotating encrypted files
• updatekeys uses .sops.yaml as the recipient source of truth and does not rotate secret values or data encryption keys
• keyseal commit stages only Keyseal-managed files, not the whole repo
• rollback restores the encrypted file from Git history; --dry-run previews safely

For exact command behavior and more examples, see the Command Reference, Configuration Reference, and Troubleshooting wiki pages.

Version reporting

keyseal --version
keyseal version
keyseal version --short

Release builds stamp version, commit, and build date metadata via Go linker flags. Local builds default to dev, unknown, and unknown unless you pass VERSION, COMMIT, and DATE. When Git metadata is available, local builds use the latest v* tag and the short current commit.

Release artifacts

make dist VERSION=v1.0.0 COMMIT=$(git rev-parse --short HEAD) DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

make dist builds tar.gz archives, .deb and .rpm packages for Linux (amd64, arm64), and a single SHA256 checksums file covering all artifacts to dist/. Linux packages require nfpm to be installed.

Development

make fmt
make check
make test
make build

Contributor-oriented detail is available in the Contributing wiki page.

Origin

Keyseal was born out of a real production need: managing encrypted secret files safely and predictably with SOPS-compatible encryption, age keys, and Git. It is a small, focused tool for teams that want Git-backed secret workflows without the overhead of a hosted platform.

Licensing

This package is licensed under GPL-3.0-only (GNU General Public License v3.0 only).

If you distribute this package, modifications, or derivative works, review the GPLv3 obligations first to make sure your usage and distribution model remain compliant.

See LICENSE for the full license text.