Provider fallback

Secrets may live in different stores across environments or during a migration. An ordered provider route lets SecretSpec read from the first store that has a value while keeping one store as the write target.

Provider selection order

SecretSpec selects each secret’s route in this order:

The --provider command-line option.
The SECRETSPEC_PROVIDER environment variable.
The secret’s effective providers list after profile inheritance and [profiles.<name>.defaults] are applied.
The default provider in the user configuration.

--provider and SECRETSPEC_PROVIDER replace the configured route for every secret. Without an override or effective providers list, SecretSpec uses the user-level default.

Ordered fallback routes

Provider lists accept aliases, provider names, and inline URIs. Reads try them from left to right:

[providers]
prod_vault = "onepassword://Production"
local = "keyring://"

[profiles.production.defaults]
providers = ["prod_vault", "local"]

[profiles.production]
# Uses the profile default: prod_vault, then local.
DATABASE_URL = { description = "Production database" }

# Overrides the profile default and reads only from the environment.
DEPLOY_TOKEN = { description = "Deployment token", providers = ["env"] }

Reads stop at the first value. Writes and generated values go only to the first provider in the effective list (prod_vault above).

Later entries are resolved, constructed, and contacted only when needed. If a reached provider cannot be resolved, constructed, or read, SecretSpec warns and continues. If every reached provider fails, the operation returns a provider error rather than reporting the secret as absent.

Cached routes

SecretSpec 0.17+ can place a local cache before an ordered route. See Provider caching for configuration and freshness rules.

Next steps

Learn how to configure provider aliases.
Learn how Profiles apply provider defaults.