SecretSpec

Declarative secrets, every environment, any provider.

SecretSpec separates the declaration of what secrets an application needs from where they are stored, enabling portable applications that work across different secret storage backends without code changes.

Documentation | Quick Start | Announcement Blog Post

Features

• Declarative Configuration: Define your secrets in secretspec.toml with descriptions and requirements
• Multiple Provider Backends: Keyring, .env, OnePassword, LastPass, and environment variables
• 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.)
• Configuration Inheritance: Extend and override shared configurations using the extends feature
• Discovery: secretspec init to discover secrets from existing .env files

Quick Start

# 1. Initialize secretspec.toml (discovers secrets from .env)
$ secretspec init
✓ Created secretspec.toml with 0 secrets

Next steps:
  1. secretspec config init    # Set up user configuration
  2. secretspec check          # Verify all secrets are set
  3. secretspec run -- your-command  # Run with secrets

# 2. Set up provider backend
$ secretspec config init
? Select your preferred provider backend:
> onepassword: OnePassword password manager
  dotenv: Traditional .env files
  env: Read-only environment variables
  keyring: Uses system keychain (Recommended)
  lastpass: LastPass password manager
? Select your default profile:
> development
  default
  none
✓ Configuration saved to /home/user/.config/secretspec/config.toml

# 3. Check and configure secrets
$ secretspec check

# 4. Run your application with secrets
$ secretspec run -- npm start

# Or with a specific profile and provider
$ secretspec run --profile production --provider dotenv -- npm start

See the Quick Start Guide for detailed instructions.

Installation

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

See the installation guide for more options including Nix, Homebrew, and Docker.

Configuration

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

[project]
name = "my-app"  # Inferred from current directory name when using `secretspec init`
revision = "1.0"
# Optional: extend other configuration files
extends = ["../shared/common", "../shared/auth"]

[profiles.default]
DATABASE_URL = { description = "PostgreSQL connection string", required = true }
REDIS_URL = { description = "Redis connection string", required = false, default = "redis://localhost:6379" }

# Profile-specific configurations
[profiles.development]
DATABASE_URL = { description = "PostgreSQL connection string", required = false, default = "sqlite://./dev.db" }
REDIS_URL = { description = "Redis connection string", required = false, default = "redis://localhost:6379" }

[profiles.production]
DATABASE_URL = { description = "PostgreSQL connection string", required = true }
REDIS_URL = { description = "Redis connection string", required = true }

See the configuration reference for all available options.

Profiles

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

# Use specific profile
$ secretspec run --profile development -- npm start
$ secretspec run --profile production -- npm start

# Set default profile
$ secretspec config init

Learn more about profiles and profile selection.

Providers

SecretSpec supports multiple storage backends for secrets:

• Keyring - System credential store (recommended)
• .env files - Traditional dotenv files
• Environment variables - Read-only for CI/CD
• OnePassword - Team secret management
• LastPass - Cloud password manager

# Use specific provider
$ secretspec run --provider keyring -- npm start
$ secretspec run --provider dotenv -- npm start

# Configure default provider
$ secretspec config init

See provider concepts and provider reference for details.

Rust SDK

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

// Generate typed structs from secretspec.toml
secretspec_derive::declare_secrets!("secretspec.toml");

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 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<String>
    if let Some(redis) = &secrets.redis_url {
        println!("Redis: {}", redis);
    }

    Ok(())
}

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

CLI Reference

Common commands:

# Initialize and configure
secretspec init                    # Create secretspec.toml
secretspec config init            # Set up user configuration

# Manage secrets
secretspec check                  # Verify all secrets are set
secretspec set KEY               # Set a secret interactively
secretspec get KEY               # Retrieve a secret
secretspec list                  # List all configured secrets
secretspec import PROVIDER       # Import secrets from another provider

# Run with secrets
secretspec run -- command        # Run command with secrets as env vars

See the full CLI reference for all commands and options.

Contributing

We welcome contributions! Areas where you can help:

• New provider backends - See the provider implementation guide
• Language SDKs - Help us support more languages beyond Rust
• Package managers - Get SecretSpec into your favorite package manager
• Documentation - Improve guides and examples

See our GitHub repository to get started.

License

This project is licensed under the Apache License 2.0.