Concepts Overview
How SecretSpec’s core concepts work together
SecretSpec is built around three core ideas that separate concerns and keep your secrets portable across environments.
Declare what you need
A secretspec.toml lists the abstract secrets your project depends on, with descriptions, defaults, and whether they are required. This file lives in version control so every developer and CI system sees the same requirements.
Use profiles for environments
Profiles let you vary secret requirements per environment. A production profile can enforce strict requirements while a development profile provides safe defaults. Non-default profiles inherit from default when it exists, so you only specify what changes; SecretSpec 0.19+ also supports standalone profiles that opt out of this inheritance.
Store secrets anywhere with providers
Providers are pluggable backends (keyring, dotenv, 1Password, Vault, etc.) that handle actual storage and retrieval. The same secretspec.toml works regardless of where secrets are stored, and you can swap providers without changing your project configuration.
How they connect
secretspec.toml Profile selected Provider resolves
(what you need) --> (which requirements) --> (where to get values)- You declare secrets in
secretspec.toml - The active profile determines which secrets are required and what defaults apply
- The provider retrieves (or stores) the actual values
Each concern is independent: you can change your storage backend without touching profile definitions, or add a new environment without modifying provider configuration.
Additional concepts
- Configuration Inheritance lets projects share common secret definitions via
extends - Scopes (0.17+) let each service or task resolve only its declared subset of a profile
- Secret Generation auto-creates passwords, tokens, and keys when secrets are missing
- Composed Secrets (0.16+) derive read-only values from other declared secrets
Last updated Oct 11, 2026