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

*If default is provided, required defaults to false
**Only valid when required = false

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" }

# 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 }
API_URL = { description = "Production API endpoint", required = true }
SENTRY_DSN = { description = "Error tracking service", required = true }
REDIS_URL = { description = "Redis cache connection", required = 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