SecretSpec is a declarative secrets manager built by Cachix (the people behind devenv). Its one idea: separate the declaration of a secret from its storage.

You commit a secretspec.toml that says which secrets the application needs — names, descriptions, requiredness — while the values themselves live in a provider: the system keyring, 1Password, Vault, SOPS, an age file, AWS Secrets Manager, and ~25 others. Nothing secret enters git, and no .env file has to be passed around.

It is Apache-2.0, written in Rust, and the tagline is "a declarative interface for every secret provider."

Binaries installed by the script self-update with secretspec-update.

The README states it bluntly: secrets end up in .env files that get committed, shared over Slack, or copy-pasted between machines. Every developer has their own version, nobody knows which secrets are actually needed, and onboarding means asking around for values.

SecretSpec turns that implicit knowledge into a reviewable, version-controlled manifest. secretspec check then becomes a real answer to "do I have everything I need to run this?" — which direnv and plain dotenv files cannot give you, because they only carry values, never a contract.

The project positions itself as the application-facing layer of a secrets system, not a replacement for Vault or 1Password. It defines portable application semantics; each provider still decides how values are stored, protected and operated.

secretspec config global init --provider env --profile default does the same non-interactively.

The default profile is inherited by all others unless a profile opts out with [profiles.<name>.defaults] inherit = false (0.19+). A [profiles.<name>.defaults] table can also set profile-wide required, default and providers.

Profiles select environments; scopes (0.17+) cut across them, narrowing which secrets a given consumer sees:

check, run and export honour scopes; set and import deliberately ignore them so you cannot accidentally cripple a write. The docs are explicit that a scope is containment, not an authorization boundary — a process holding the config and the provider credentials can resolve the other scopes itself.

A provider can be named three ways: a bare name (keyring, vault), a URI (dotenv://.env.local, onepassword://Production), or an alias declared in [providers]. Project aliases beat user-level ones from ~/.config/secretspec/config.toml.

Roughly thirty backends ship in-tree:

Unless a ref overrides it, secrets are addressed by the convention secretspec/{project}/{profile}/{key} — a Vault KV path, a 1Password secure note, a pass entry, and so on. Azure Key Vault base32-encodes the components because of its charset limits; GCSM flattens to secretspec2--{project}--{profile}--{key}.

Swapping backend is a flag, never a code change:

Aliases can compose. A chain tries each route in order:

Provider credentials are themselves resolved from a provider, so the 1Password token or Vault role ID never sits in a shell profile — and the application never sees it, only the secret it unlocks:

secretspec config provider login bws stores it. Caching (0.17+) puts a local store in front of a slow remote one:

Only providers that support deletion can back a cache (keyring, pass, gopass, dotenv, Vault/OpenBao KV v2, and 0.20+ age and Azure App Config). Entries are fingerprinted against the route, so changing the URI, ref or max_age invalidates them; secretspec cache clear [KEY] does it by hand. Cache failures warn but never block the authoritative read.

Missing secrets can be created rather than asked for. Generation is idempotent — it fires only when the secret is absent, and never overwrites:

Defaults are 32 alphanumeric chars for password, 32 bytes for hex/base64, 2048-bit PKCS1 PEM for rsa_private_key. Paired with the null provider this becomes ephemeral generation — a fresh value every resolution, stored nowhere.

Composed secrets (0.16+) build a read-only derived value out of other declared ones, which is how you avoid storing a whole DSN alongside its parts:

References are order-independent and must be ${UPPERCASE_NAME}.

On by default since 0.17. Every get, set, check, run, import, export, delete and cache operation is recorded locally — metadata only, never values, with credentials in provider URIs redacted.

Records carry project, profile, secret names, provider, outcome (found, missing, default, written, deleted, started, error), timestamp, OS user and a supplied reason. The log is JSON Lines at ~/.local/state/secretspec/audit.log, mode 0600, capped at 1 MiB with truncate-and-restart instead of rotation.

Notably, the actor field detects coding agents and sets an is_agent flag. require_reason defaults to "agents", meaning an agent-driven session must justify itself via --reason / SECRETSPEC_REASON / the SDK before it can read anything; require_reason = true demands it from every caller.

Auditing is configured only in the user-global config, never the project file — a repository cannot switch off its own logging:

Beyond init / check / run:

Global flags: -f/--file, --reason, and --caller / --caller-version / --caller-operation / --caller-resource for integrations identifying themselves to the audit log. Environment overrides: SECRETSPEC_PROFILE, SECRETSPEC_PROVIDER, SECRETSPEC_SCOPE, SECRETSPEC_FILE, SECRETSPEC_REASON.

The Rust SDK generates typed structs from the manifest at compile time — optional secrets become Option<String>:

Eight further SDKs are thin clients over the same native core, so providers, chains, profiles and generators behave identically with no per-language resolution logic: Python (pyo3), Node.js/TypeScript (napi-rs), Go (purego over the secretspec-ffi C ABI, no cgo), Ruby (C extension), PHP (ext-php-rs, ext-ffi fallback), C# (P/Invoke via NuGet, 0.16+), Swift (SwiftPM XCFramework, 0.18+), and Haskell.

For typed access in a language without a first-class SDK, secretspec schema emits JSON Schema you can run through quicktype.

devenv / Nix — the original driver for the project. Enable it in devenv.yaml and reference resolved secrets from devenv.nix, letting each machine pick its own provider without touching shared config:

GitHub Actions — cachix/secretspec-action installs the CLI and runs secretspec export --format gha, which masks every value in the runner log, appends them to $GITHUB_ENV, and fails the step up front if a required secret is missing. Works identically under Forgejo Actions.

With Vault or OpenBao the runner's OIDC token is exchanged for a short-lived client token, so no long-lived credential is stored on the CI platform at all. Other CI systems just call secretspec run -- or secretspec export directly.

Git credential helper (0.20+) — authenticates HTTPS clone/fetch/push and git send-email SMTP through any provider, instead of duplicating tokens into a second credential store. The URL is matched before the provider is loaded, so a token for https://github.com is never returned for another host or for plain HTTP.

The project started in July 2025 and is pre-1.0 — the latest crates.io release is 0.19.1 (August 2026), with 0.20 features (Fly.io, Azure App Configuration, the git helper, static musl binaries for Alpine) documented ahead of the tag. Version gates are dense enough that the docs annotate nearly every feature with the release that introduced it; check them before relying on something.

Worth knowing: