secretspec.toml Reference

secretspec.toml Reference

The secretspec.toml file defines project-specific secret requirements. This file should be checked into version control.

[project] Section

[project]
name = "my-app"              # Project name (required)
revision = "1.0"             # Format version (required, must be "1.0")
extends = ["../shared"]      # Paths to parent configs for inheritance (optional)

Field	Type	Required	Description
name	string	Yes	Project identifier
revision	string	Yes	Format version (must be “1.0”)
extends	array[string]	No	Paths to parent configuration files

[profiles.*] Section

Defines secret variables for different environments. At least a [profiles.default] section is required.

[profiles.default]           # Default profile (required)
DATABASE_URL = { description = "PostgreSQL connection", required = true }
API_KEY = { description = "External API key", required = true }
REDIS_URL = { description = "Redis cache", required = false, default = "redis://localhost:6379" }

[profiles.production]        # Additional profile (optional)
DATABASE_URL = { description = "Production database", required = true }

Secret Variable Options

Each secret variable is defined as a table with the following fields:

Field	Type	Required	Description
description	string	Yes	Human-readable description of the secret
required	boolean	No*	Whether the value must be provided (default: true)
default	string	No**	Default value if not provided
providers	array[string]	No	List of provider aliases to use in fallback order
as_path	boolean	No	Write secret to temp file and return file path (default: false)
type	string	No***	Secret type for generation: password, hex, base64, uuid, command, rsa_private_key
generate	boolean or table	No***	Enable auto-generation when secret is missing

*If default is provided, required defaults to false **Only valid when required = false ***type is required when generate is enabled; generate and default cannot both be set

Complete Example

secretspec.toml

[project]
name = "web-api"
revision = "1.0"
extends = ["../shared/secretspec.toml"]  # Optional inheritance

# Default profile - always loaded first
[profiles.default]
APP_NAME = { description = "Application name", required = false, default = "MyApp" }
LOG_LEVEL = { description = "Log verbosity", required = false, default = "info" }
GITHUB_TOKEN = { description = "GitHub token", required = true, providers = ["env"] }

# Development profile - extends default
[profiles.development]
DATABASE_URL = { description = "Database connection", required = false, default = "sqlite://./dev.db" }
API_URL = { description = "API endpoint", required = false, default = "http://localhost:3000" }
DEBUG = { description = "Debug mode", required = false, default = "true" }

# Production profile - extends default
[profiles.production]
DATABASE_URL = { description = "PostgreSQL cluster connection", required = true, providers = ["prod_vault", "keyring"] }
API_URL = { description = "Production API endpoint", required = true }
SENTRY_DSN = { description = "Error tracking service", required = true, providers = ["shared_vault"] }
REDIS_URL = { description = "Redis cache connection", required = true }

Provider Aliases

When using per-secret provider configuration, provider aliases must be defined in your user configuration file at ~/.config/secretspec/config.toml:

[defaults]
provider = "keyring"

[providers]
prod_vault = "onepassword://vault/Production"
shared_vault = "onepassword://vault/Shared"
env = "env://"

Manage provider aliases using CLI commands:

# Add a provider alias
$ secretspec config provider add prod_vault "onepassword://vault/Production"

# List all aliases
$ secretspec config provider list

# Remove an alias
$ secretspec config provider remove prod_vault

as_path Option

When as_path = true, the secret value is written to a temporary file and the file path is returned instead of the value:

[profiles.default]
TLS_CERT = { description = "TLS certificate", as_path = true }
GOOGLE_APPLICATION_CREDENTIALS = { description = "GCP service account", as_path = true }

Context	Behavior
CLI (get, check, run)	Files are persisted (not deleted after command exits)
Rust SDK	Files cleaned up when ValidatedSecrets is dropped; use keep_temp_files() to persist
Rust SDK types	PathBuf or Option<PathBuf> instead of String

Secret Generation

Note

Secret generation is available since version 0.7.

When type and generate are set, missing secrets are automatically generated during check or run and stored via the configured provider:

[profiles.default]
# Simple: generate with type defaults
DB_PASSWORD = { description = "Database password", type = "password", generate = true }
REQUEST_ID = { description = "Request ID prefix", type = "uuid", generate = true }

# Custom options
API_TOKEN = { description = "API token", type = "hex", generate = { bytes = 32 } }
SESSION_KEY = { description = "Session key", type = "base64", generate = { bytes = 64 } }

# Shell command
MONGO_KEY = { description = "MongoDB keyfile", type = "command", generate = { command = "openssl rand -base64 765" } }

# RSA private key (PKCS1 PEM)
JWT_SIGNING_KEY = { description = "JWT signing key", type = "rsa_private_key", generate = true }

# Type without generate: informational only, no auto-generation
MANUAL_SECRET = { description = "Manually managed", type = "password" }

Generation Types

Type	Default Output	Options
password	32 alphanumeric chars	length (int), charset ("alphanumeric" or "ascii")
hex	64 hex chars (32 bytes)	bytes (int)
base64	44 chars (32 bytes)	bytes (int)
uuid	UUID v4 (36 chars)	none
command	stdout of command	command (string, required)
rsa_private_key	2048-bit RSA private key (PKCS1 PEM)	bits (int)

Behavior

• Generation only triggers when a secret is missing — existing secrets are never overwritten
• Generated values are stored via the secret’s configured provider (or the default provider)
• Subsequent runs find the stored value and skip generation (idempotent)
• generate and default cannot both be set on the same secret
• type = "command" requires generate = { command = "..." } (not just generate = true)

Profile Inheritance

• All profiles automatically inherit from [profiles.default]
• Profile-specific values override default values
• Use the extends field in [project] to inherit from other secretspec.toml files