secretspec

Stop committing secrets to git and putting them to .env files.

Secrets end up in .env files that get accidentally committed, shared over Slack, or copy pasted between machines. Each developer has their own version, nobody knows which secrets are actually needed, and onboarding means asking around for values.

SecretSpec fixes this by separating secret declaration from secret storage. You commit a secretspec.toml that declares what secrets your application needs, while the actual values live in a secure provider like your system keyring, 1Password, or any other backend. No secrets in git, no .env files to leak.

Documentation | Quick Start | Announcement Blog Post

Features

• Declarative Configuration: Define your secrets in secretspec.toml with descriptions and requirements
• Multiple Provider Backends:
  • Keyring
  • KeePass KDBX (0.17+)
  • .env
  • plaintext files (0.19+)
  • 1Password
  • Keeper Secrets Manager (0.18+)
  • LastPass
  • Dashlane (0.18+)
  • Pass
  • Gopass (0.15+)
  • Proton Pass
  • Passbolt (0.19+)
  • environment variables
  • null (0.19+)
  • systemd credentials (0.17+)
  • Fly.io application secrets (0.20+, write-only)
  • Cloudflare Secrets Store (0.20+, write-only)
  • Google Cloud Secret Manager
  • AWS Secrets Manager
  • AWS Systems Manager Parameter Store (0.18+)
  • Scaleway Secret Manager (0.17+)
  • Vault
  • OpenBao (0.17+)
  • Bitwarden Password Manager (0.18+)
  • Bitwarden Secrets Manager (official bws CLI required in SecretSpec 0.17+)
  • Azure Key Vault
  • Azure App Configuration (0.20+)
  • Infisical (0.16+)
  • EJSON (0.20+, read-only)
  • age (0.17+)
  • SOPS (0.17+)
  • Kubernetes (0.20+)
• Type-Safe Rust SDK: Generate strongly-typed structs from your secretspec.toml for compile-time safety
• Profile Support: Override secret requirements and defaults per profile (development, production, etc.)
• Secret Generation: Auto-generate passwords, tokens, UUIDs, and more when secrets are missing — including pure-Rust OpenPGP and OpenSSH private keys in 0.21+
• Run prompts (0.19+): Set prompt = true to request a hidden missing value; writable providers save it, while null keeps it invocation-only
• Composed Secrets (0.16+): Derive read-only values such as DSNs from declared secrets with strict, order-independent ${UPPERCASE_NAME} references
• Configuration Inheritance: Extend and override shared configurations using the extends feature
• Audit Logging: Every secret access recorded locally (who, when, why, outcome) — on by default, secret values never logged
• Docker credential helper (0.20+): Authenticate registry pulls and pushes through any SecretSpec provider
• Git credential helper (0.20+): Authenticate Git HTTPS and git send-email SMTP operations through any SecretSpec provider
• Discovery: secretspec init to discover secrets from existing .env files
• Claude Code credential integration (0.21+): Configure, store, and remove API or gateway credentials through Claude Code's native apiKeyHelper

Quick Start

…

See the Quick Start Guide for detailed instructions.

Installation

curl -sSL https://install.secretspec.dev | sh

SecretSpec 0.20+ provides static musl CLI binaries for x64 and arm64 Linux, so the installer works directly on Alpine without a glibc compatibility layer.

See the installation guide for more options including Nix and Devenv.

Configuration

Each project has a secretspec.toml file that declares the required secrets:

…

SecretSpec 0.19+ can map one logical secret to different native coordinates per provider alias, including independent import source and destination refs:

[providers]
remote = { uri = "onepassword://Production", ref = { item = "{project}-{profile}", field = "{key}" } }
local = "keyring://"

[profiles.production]
API_KEY = { description = "API key", providers = ["local"], refs = { remote = { item = "legacy-api", field = "token" } } }

See the configuration reference for all available options.

Profiles

Profiles allow you to define different secret requirements for each environment (development, production, etc.):

$ secretspec run --profile development -- npm start
$ secretspec run --profile production -- npm start

# Set a user-global default profile (0.17+)
$ secretspec config global init

# SecretSpec 0.17+: set provider and profile defaults without prompting
$ secretspec config global init --provider env --profile default

Learn more about profiles and profile selection.

Providers

SecretSpec supports multiple storage backends for secrets:

• Keyring - System credential store (recommended)
• KeePass KDBX (0.17+) - Local KeePass-compatible encrypted database
• .env files - Traditional dotenv files
• Plaintext files (0.19+) - One UTF-8 file per secret in a local directory tree
• Environment variables - Read-only for CI/CD
• Null (0.19+) - Use committed defaults, ephemeral generation, or ephemeral run prompts without secret storage
• systemd credentials (0.17+) - Read-only credentials passed to the current service
• Fly.io application secrets (0.20+) - Write and delete app secrets through flyctl; Fly.io does not expose plaintext values
• Cloudflare Secrets Store (0.20+) - Publish and delete account secrets through Cloudflare's API; plaintext is available only to bound Cloudflare services
• Pass - Unix password manager with GPG encryption
• Gopass (0.15+) - GPG-based password manager with git-synced password store
• Proton Pass - End-to-end encrypted via Proton's official pass-cli
• Passbolt (0.19+) - Self-hosted Passbolt through go-passbolt-cli
• 1Password - Team secret management
• Keeper Secrets Manager (0.18+) - Machine secrets through Keeper's official Rust SDK
• LastPass - Cloud password manager
• Dashlane (0.18+) - Read-only access to a Dashlane vault via the dcli CLI
• Google Cloud Secret Manager - GCP secret management
• AWS Secrets Manager - AWS secret management
• AWS Systems Manager Parameter Store (0.18+) - Encrypted hierarchical parameters in AWS
• Scaleway Secret Manager (0.17+) - Scaleway secret management
• Vault - HashiCorp Vault KV engine
• OpenBao (0.17+) - OpenBao KV integration; SecretSpec 0.16 accepts openbao:// through the Vault provider
• Bitwarden Password Manager (0.18+) - Bitwarden Password Manager vault via the bw CLI
• Bitwarden Secrets Manager - Bitwarden Secrets Manager integration (official bws CLI required in SecretSpec 0.17+)
• Azure Key Vault - Azure secret management
• Azure App Configuration (0.20+) - Azure key-value management with Key Vault reference resolution
• Infisical (0.16+) - Infisical secret management
• EJSON (0.20+) - Read-only EJSON encrypted files with an explicit private-key provider credential
• age (0.17+) - age-encrypted file
• SOPS (0.17+) - SOPS-encrypted files
• Kubernetes (0.20+) - Kubernetes

$ secretspec run --provider keyring -- npm start
$ secretspec run --provider dotenv -- npm start

# Configure a user-global default provider (0.17+)
$ secretspec config global init

See provider concepts and provider reference for details.

Rust SDK

Generate strongly-typed Rust structs from your secretspec.toml:

secretspec_derive::declare_secrets!("secretspec.toml");

fn main() -> Result> {
    // Load secrets with type safety
    let secrets = SecretSpec::load(Provider::Keyring)?;

    // Access secrets as struct fields
    println!("Database: {}", secrets.database_url);

    // Optional secrets are Option
    if let Some(redis) = &secrets.redis_url {
        println!("Redis: {}", redis);
    }

    Ok(())
}

See the Rust SDK documentation for advanced usage including profile-specific types.

Language SDKs

Beyond Rust, SecretSpec ships SDKs for other languages. Each is a thin client over the same native core, so every provider, chain, profile, and generator works identically with no per-language resolution logic:

The shared embedded ABI is named libsecretspec in SecretSpec 0.20+; i