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)require_reason = "agents"    # When to require a reason for secret access (optional)

The 1.0 revision is backward compatible: newer SecretSpec versions continue to support existing revision = "1.0" configurations, although they may add features to the revision before SecretSpec 1.0 is released. With the SecretSpec 1.0 release, revision 1.0 will be finalized. Later configuration format changes may be introduced under new revision numbers.

Requiring a reason for secret access

require_reason controls when secretspec demands a reason for accessing secrets. It accepts three values:

The policy is enforced at SecretSpec’s secret-access entry points and travels with the checked-in secretspec.toml. With true, every caller using the manifest must supply a reason before SecretSpec proceeds:

# In a session SecretSpec detects as an agent, with the default "agents" policy:$ secretspec run -- ./deploy.shError: Accessing secrets requires a reason. Provide one with --reason "<why...>" ...
$ secretspec run --reason "Deploy web frontend" -- ./deploy.sh   # ok

Terminal window

Agent detection. secretspec delegates heuristic detection of known agents to the detect-coding-agent crate, which maintains the per-tool signal list (Claude Code, Cursor, Codex, Gemini CLI, Copilot, and more). It treats autonomous and hybrid environments as agents but not human-driven interactive editors. In addition, secretspec checks its own SECRETSPEC_AGENT environment variable as an explicit opt-in:

# Mark any harness the detector does not recognize as an agent:$ export SECRETSPEC_AGENT=1

Terminal window

Cooperative harnesses that are not auto-detected can set SECRETSPEC_AGENT=1. Do not rely on a caller to identify itself when a reason is mandatory; use require_reason = true instead.

The reason is recorded in secretspec’s own audit log and is also forwarded to providers that support auditing (e.g. the Proton Pass provider records it in the agent audit log).

[profiles.*] Section

Defines secret variables for different environments. At least one profile is required. A default profile is optional; when present, other profiles inherit from it unless they opt out in SecretSpec 0.19+.

[profiles.default]           # Optional shared base profileDATABASE_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 = { required = true } # description inherited from default

Profile defaults

[profiles.\<name\>.defaults] supplies settings for secrets declared in that profile:

In SecretSpec 0.19+, set inherit = false for a standalone profile:

[profiles.deployment.defaults]inherit = false
[profiles.deployment]DEPLOY_TOKEN = { description = "Deployment credential", required = true }

This excludes every [profiles.default] declaration and prevents explicitly redeclared secrets from inheriting omitted fields. The setting has no effect on the default profile itself. A standalone profile must declare at least one secret.

Cross-secret presence constraints

A profile can require alternative credentials by assigning secrets to a named group:

[profiles.default]PASSWORD = { description = "Account password", required = { at_least_one = "account_auth" } }ACCESS_TOKEN = { description = "Personal access token", required = { at_least_one = "account_auth" } }
GITHUB_TOKEN = { description = "GitHub token", required = { exactly_one = "github_auth" } }GITHUB_APP_KEY = { description = "GitHub App private key", required = { exactly_one = "github_auth" } }

at_least_one requires one or more group members to resolve; exactly_one requires one. Each field also accepts an array of group names for overlapping groups. Groups must contain at least two secrets and cannot mix modes. Group members are individually optional.

Under a scope, a group is judged over the members that scope exposes, so a scoped consumer never inherits a guarantee that rests on a secret it cannot see.

Secret Variable Options

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

Field notes:

• description is required on the effective secret. An inheriting profile may omit it when a matching default declaration supplies it. A standalone profile using inherit = false (0.19+) must supply its own description.
• required defaults to false when default is provided. In 0.17+, its table form accepts at_least_one and exactly_one as a group name or array of names.
• default is invalid with an explicit required = true. A defaulted secret is guaranteed to be present in successful resolution and generated types, even though the provider does not have to supply it.
• type is required when generate is enabled.
• generate and default cannot both be set.
• prompt = true (0.19+) is for individually required secrets and cannot be combined with default, enabled generate, extract, or composed.
• extract (0.19+) is read-only and cannot be combined with enabled generate.

Composed Secrets

A composed secret derives a value from other secrets in the effective profile. See Composed Secrets for the dependency model, CLI behavior, profile inheritance, and the differences from dotenv expansion:

[profiles.default]DB_USER = { description = "Database user" }DB_PASSWORD = { description = "Database password" }DB_HOST = { description = "Database host" }DATABASE_URL = { description = "PostgreSQL DSN", composed = "postgres://${DB_USER}:${DB_PASSWORD}@${DB_HOST}/app" }

References form a static dependency graph. Declaration order does not matter, and composed secrets may reference other composed secrets. SecretSpec rejects unknown references, cycles, malformed references, and source conflicts while loading the manifest. A composed secret is read-only and cannot also set default, providers, ref, refs (0.19+), type, enabled generate, encoding (0.19+), or extract (0.19+).

Composition intentionally does not implement dotenv or shell expansion:

• only ${UPPERCASE_NAME} is a reference, and the name must match [A-Z][A-Z0-9_]* and identify a declared secret;
• ambient environment variables are never consulted;
• fallback operators such as ${NAME:-fallback}, commands, and recursive expansion are unsupported;
• inserted values are opaque and are never scanned again;
• $$ produces a literal $ ($${NAME} renders ${NAME}), while ordinary braces are literal;
• a missing dependency makes a required composition missing, while a required = false composition is omitted;
• empty values remain empty and are distinct from missing values.

If a dependency uses as_path = true, its exported temporary-file path is the text inserted into the composed value. Applying as_path = true to the composed secret materializes the final combined value.

Composition is raw string concatenation. SecretSpec cannot know whether a component occupies a URL username, password, host, path, query, or structured document position, so it does not URL-encode or JSON-encode components. Store components in the form required by the target format; use secretspec export --format json when exporting the resolved secret map as JSON.

[scopes] Section

See Scopes for the conceptual model and a focused guide to narrowing services and tasks. This section specifies the complete configuration and resolution behavior.

Scopes name membership-only subsets of a profile’s secrets, so a single service or task resolves only what it declares instead of the entire profile. They are orthogonal to profiles: a profile decides how each secret resolves (required, default, providers, references, generation, prompts (0.19+), as_path, encoding (0.19+), extract (0.19+), and the storage namespace); a scope only decides which secrets take part in a given resolution.

[profiles.default]DATABASE_URL = { description = "Database", required = true }API_KEY      = { description = "API key", required = true }QUEUE_TOKEN  = { description = "Queue token", required = true }
[scopes.api]secrets = ["DATABASE_URL", "API_KEY"]
[scopes.worker]secrets = ["DATABASE_URL", "QUEUE_TOKEN"]

$ secretspec run --scope api    -- ./api      # sees DATABASE_URL, API_KEY
$ secretspec run --scope worker -- ./worker   # sees DATABASE_URL, QUEUE_TOKEN
$ secretspec check  --scope api
$ secretspec export --scope worker --format dotenv

Terminal window

Behavior:

• No scope resolves the complete profile, exactly as before scopes existed.
• Selecting a scope resolves the intersection of the merged profile and the scope’s secrets list — the visible set. A secret the profile does not declare is simply absent from that resolution rather than an error, so a scope can be reused across profiles that declare different subsets.
• A required secret excluded by the active scope does not block resolution — it is not part of the scoped set.
• Composed secrets resolve their inputs without exposing them. When a visible composed secret references secrets the scope leaves out (for example DATABASE_URL built from DB_USER and DB_PASSWORD), those dependencies are fetched to build the composition and then dropped from the output — the child sees DATABASE_URL, never DB_USER/DB_PASSWORD. A secret that is neither visible nor a dependency of a visible secret is never fetched, so no provider is contacted for it.
• A scope does not change a secret’s storage address ({project}/{profile}/{key}); it only narrows the set.
• Presence groups are judged over the visible members. A required = { at_least_one = … } or { exactly_one = … } group (see Cross-secret presence constraints) is evaluated against the members the scope actually exposes. A group with no visible member is not that consumer’s concern and is not enforced. A group with some visible members is enforced over those alone, so a scope never inherits a guarantee that rests on a secret it hides — if at_least_one = "cloud" is satisfied profile-wide by GCP_KEY, a scope showing only AWS_KEY still fails when AWS_KEY is absent. exactly_one remains enforced whenever two visible members are both present: scoping narrows what is judged, never whether it is judged. A secret fetched only as a hidden composition input does not count as present, and a violation message names only visible members. The reverse case cannot be detected, because a secret the scope hides is never fetched: if exactly_one = "token" is violated profile-wide by both PRIMARY and FALLBACK being present, a scope showing only PRIMARY reports success. A scoped check validates the scoped consumer, not the profile; run an unscoped secretspec check to validate the profile as a whole.
• run --scope removes every manifest-declared secret the scope does not admit from the launched command’s environment, across all profiles rather than only the selected one, even if the parent shell already exported them, so a value inherited from another profile cannot leak into the child. Membership decides this, so a secret the scope lists survives even when the selected profile does not declare it (see the admitted rule below). This is secret minimization, not an authorization boundary: a process that still holds provider credentials could resolve another scope itself.
• export --scope emits the visible set but unsets nothing, since its output formats have no way to express an unset. Narrowing an environment that already holds a wider set therefore needs run --scope: after eval "$(secretspec export)", a later eval "$(secretspec export --scope api)" leaves the previously exported values live in the shell.
• An empty scope (or a scope whose intersection with the profile is empty) resolves to nothing and contacts no provider.
• Diagnostics do not name what the scope hides. A provider warning about a hidden composition input calls it a hidden composition input rather than naming it, matching the way prompting is filtered, so a failing provider cannot disclose the very name the output filter removed. A visible secret is still named. This covers secretspec’s own messages; a provider’s error text is written by that provider and may still mention the address it searched.
• Audit records what was read, not what was exposed: a scoped check logs the accessed set, including a composition input the scope hides, since the point of the log is to capture provider access. A run event logs what it injected — the visible set. Scoped check, run, and export events also carry the selected scope name (SecretSpec 0.17+).
• An as_path secret’s resolved value is its temp-file path, so a visible composition built from a hidden as_path input embeds that path. The file stays alive for the duration of the command rather than being cleaned up with the hidden secret, so the path resolves. The hidden input is still absent from the environment; only its content, in the form the composition derived, is reachable — the same contract as a composed DSN that embeds a password.
• A secret the scope admits is never scrubbed from run, whether it fails to resolve (an optional secret with no stored value) or the selected profile does not declare it at all. A value the parent exported is inherited exactly as it would be without a scope; scoping changes which secrets are in play, never the semantics of one it admits. This is what lets a single scope be reused across profiles that declare different subsets.
• Under project extends, a child [scopes.\<name\>] replaces the parent scope of the same name outright — the two secrets lists are not unioned (see Configuration Inheritance).
• Selecting an undefined scope, or a scope that lists a secret no profile declares, is a configuration error.
• A scope’s secrets list must name at least one secret, with no blank or repeated entries. An empty scope is rejected rather than treated as “resolves to nothing”: it would contact no provider, so check --scope would report a clean 0 found, 0 missing while run --scope started the command with every manifest secret scrubbed and none injected. An empty intersection between a valid scope and the selected profile is still fine, since a scope is meant to be reused across profiles that declare different subsets.

The --scope flag (and the SECRETSPEC_SCOPE environment variable) apply to check, run, and export. Scopes are a resolution-time feature of these untyped paths. The write and copy commands are unaffected: set and import ignore an ambient SECRETSPEC_SCOPE entirely, so a scope neither restricts what they may write nor narrows the secrets they list. The untyped language SDK builders also accept an explicit scope and return its name in resolve/report results, and they honor SECRETSPEC_SCOPE when given none. The typed SDK loaders generated by secretspec-derive always resolve the full profile and deliberately ignore an ambient SECRETSPEC_SCOPE, since a generated struct expects every declared field.

A blank --scope clears an inherited scope rather than being ignored: SECRETSPEC_SCOPE=api secretspec run --scope "" -- ./job resolves the whole profile and scrubs nothing. A blank SECRETSPEC_SCOPE with no flag means the same, so a CI template that materializes an unset variable as an empty string cannot silently narrow a job.

Complete Example

[project]name = "web-api"revision = "1.0"extends = ["../shared/secretspec.toml"]  # Optional inheritance
# Provider aliases used by profile provider chains[providers]prod_vault = "onepassword://Production"shared_vault = "onepassword://Shared"keyring = "keyring://"env = "env://"
# Default profile - always loaded first[profiles.default]APP_NAME = { description = "Application name", required = false, default = "MyApp" }SESSION_SECRET = { description = "Session signing secret", required = true, providers = ["shared_vault"] }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 }

secretspec.toml

Provider Aliases

Provider aliases may be declared in two places:

1. In secretspec.toml — a top-level [providers] table. Check this into version control so every team member and CI runner sees the same mapping out of the box.
2. In ~/.config/secretspec/config.toml — a per-user [defaults.providers] table for personal overrides.

On conflict the project-level alias wins, so a stale local config cannot silently shadow the team’s mapping.

[providers]prod_vault = "onepassword://Production"shared_vault = "onepassword://Shared"keyring = "keyring://"env = "env://"
[profiles.production]DATABASE_URL = { description = "Production DB", providers = ["prod_vault", "keyring"] }

secretspec.toml

[defaults]provider = "keyring"
[defaults.providers]prod_vault = "onepassword://Production"shared_vault = "onepassword://Shared"keyring = "keyring://"env = "env://"

~/.config/secretspec/config.toml

Manage user-level aliases via CLI:

# SecretSpec 0.17+: add a provider alias to your user config$ secretspec config global provider add prod_vault "onepassword://Production"
# SecretSpec 0.17+: list all aliases known to your user config$ secretspec config global provider list
# SecretSpec 0.17+: remove an alias from your user config$ secretspec config global provider remove prod_vault

Terminal window

These explicitly scoped CLI commands operate on the user-global config only — edit secretspec.toml by hand to change project-level aliases.

Credential-aware alias values

In SecretSpec 0.15 and later, an alias value is either a bare provider URI string or a table that also declares the credentials the provider needs. Both forms are accepted in the project [providers] and user [defaults.providers] tables.

Each credentials value is either a bare provider spec — read at the convention path for the active project and profile — or a table { provider = "...", ref = { ... } } that pins the exact location with the same ref coordinates a secret uses.

[providers]keyring = "keyring://"# bare string: read access_token from keyring at the convention pathbws = { uri = "bws://project-uuid", credentials = { access_token = "keyring" } }
[providers.vault_prod]uri = "vault://secret/myapp?auth=approle"credentials = { role_id   = { provider = "onepassword", ref = { vault = "Infra", item = "vault-approle", field = "role_id" } },                secret_id = { provider = "onepassword", ref = { vault = "Infra", item = "vault-approle", field = "secret_id" } } }

secretspec.toml

Configured credentials take precedence over provider environment fallbacks, credential chains are limited to one hop, and a fetched credential is never written to the environment. Store the credentials with secretspec config provider login. See Provider credentials for the full behavior.

Starting with SecretSpec 0.19, a leaf alias may also compile logical secret names into that provider’s native coordinates. Templates expand each placeholder once; text inserted from a project, profile, or key is never interpreted as another placeholder.

[providers]remote = { uri = "onepassword://Production", ref = { item = "{project}-{profile}", field = "{key}" } }local = { uri = "dotenv://.env", ref = { item = "{key}" } }
[profiles.production]API_KEY = { description = "API key", providers = ["remote", "local"] }

secretspec.toml

Templates belong on the leaf aliases in a cached route, not on the cached alias itself. Bare provider names and literal URIs have no alias identity, so they use provider convention naming unless the secret declares legacy ref.

Inline provider cache

Use uri and cache when one provider is authoritative. credentials remains optional and configures that same provider:

[providers]local = "keyring://secretspec/cache/{project}/{profile}/{key}"azure = {  uri = "akv://team-vault",  credentials = { client_secret = "keyring" },  cache = { provider = "local", max_age = "8h" }}
[profiles.development.defaults]providers = ["azure"]

secretspec.toml

The alias remains both the selected cached route and the build key for its authoritative provider, so its configured credentials apply normally.

Cached fallback alias values

A cached fallback alias uses fallback and cache when more than one provider can answer:

[providers]azure = { uri = "akv://team-vault", credentials = { client_secret = "keyring" } }env = "env://"local = "keyring://secretspec/cache/{project}/{profile}/{key}"myprovider = { fallback = ["azure", "env"], cache = { provider = "local", max_age = "8h" } }
[profiles.development.defaults]providers = ["myprovider"]

secretspec.toml

Every cached alias is a complete route and must be the only entry when selected through providers, in any position. Fallback entries and the cache provider accept aliases, provider names, and URIs, but must resolve to leaf providers; cached aliases cannot be nested, and the cache must resolve to a different store than the route’s own authoritative providers, since it holds its entries at the same logical address. The cache provider must also be one SecretSpec can delete from — keyring, pass, gopass, dotenv, age (0.20+), Azure App Configuration (0.20+), or a Vault/OpenBao KV v2 mount — since every form of invalidation is a delete. Put credentials on leaf aliases rather than the cached fallback alias. See Provider caching for freshness, failure, invalidation, and clearing behavior.

Legacy bare-URI alias values

In SecretSpec 0.14, every alias value must be a provider URI string:

[providers]bws = "bws://project-uuid"

secretspec.toml

For example, authenticate the 0.14 BWS provider by setting its environment variable before running SecretSpec:

$ export BWS_ACCESS_TOKEN="0.your-access-token..."
$ secretspec check

Terminal window

Audit Logging

secretspec records every secret access to a local audit log. Auditing is a per-machine/operator concern — where the log lives and whether it is on — so it is configured in the user-global config, not the project’s secretspec.toml. A cloned repository therefore cannot redirect or silence your audit log. Auditing is on by default; configure it under the top-level [audit] table:

[audit]enabled = true                                   # set false to turn auditing offpath = "~/.local/state/secretspec/audit.log"     # default: per-user XDG state dirmax_size_bytes = 1048576                          # default: 1 MiB

~/.config/secretspec/config.toml

Secret values are never written to the log, and credentials embedded in provider URIs are redacted. Audit failures never block secret access. See Audit Logging for the record format and full details.

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 }

When combined with encoding (0.19+), the file contains the decoded bytes rather than the stored textual representation. When combined with extract (0.19+), it contains only the selected logical value.

Secret Encoding

encoding (0.19+) defines the textual representation stored by providers and the cache. It is independent of as_path: decoded UTF-8 remains an ordinary environment or SDK value, while arbitrary decoded bytes can be materialized to a file.

[profiles.default]# encoding is available in SecretSpec 0.19+TEXT_CONFIG = { description = "Encoded text", encoding = "base64" }KEYSTORE = { description = "Binary mTLS keystore", encoding = "base64", as_path = true }URL_SAFE_KEY = { description = "URL-safe encoded key", encoding = "base64url", as_path = true }HEX_KEY = { description = "Hex-encoded key", encoding = "hex", as_path = true }

Exactly one trailing LF or CRLF is accepted so command-captured values work without preprocessing. Other whitespace and non-alphabet characters are rejected. Without as_path = true, decoded bytes must be valid UTF-8.

secretspec set, interactive prompts, and generated secrets provide logical text; SecretSpec encodes it before writing to a provider or cache. Defaults and composed results are already logical and are not transformed. The secretspec import command copies the stored representation verbatim, avoiding double encoding.

Structured Extraction

extract (0.19+) selects one logical secret from structured text read from a provider or cache. It supports JSON (0.19+) and INI (0.20+). JSON pointer values are RFC 6901 JSON Pointers:

[providers]documents = "file:./secrets"
[profiles.default]# extract is available in SecretSpec 0.19+DB_USER = {  description = "Database user",  providers = ["documents"],  ref = { item = "application.json" },  extract = { format = "json", pointer = "/database/user" }}DB_PASSWORD = {  description = "Database password",  providers = ["documents"],  ref = { item = "application.json" },  extract = { format = "json", pointer = "/database/password" }}

Both declarations read the same document. /database/password walks nested objects, /hosts/0 selects an array element, and /a~1b/~0key selects the key ~key beneath an a/b object. The empty pointer selects the complete document.

JSON strings become their unquoted contents. Numbers, booleans, and null use their JSON spelling; objects and arrays become compact JSON. Invalid JSON or a pointer that does not match is a decoding error. Once a provider returns a document, extraction failure is not treated as a provider miss and does not continue along a fallback chain.

INI extraction (0.20+) uses the same RFC 6901 escaping for pointer segments but accepts only value selectors. /key selects an unsectioned key, while /section/key selects a key in a named section:

[profiles.default]# format = "ini" requires SecretSpec 0.20+DB_PASSWORD = {  description = "Database password",  providers = ["documents"],  ref = { item = "application.ini" },  extract = { format = "ini", pointer = "/database/password" }}

For example, that pointer reads password from [database]. An explicit [DEFAULT] section is selected as /DEFAULT/key; it is distinct from an unsectioned /key. Section and key matching is case-sensitive. ~1 selects a literal / and ~0 selects a literal ~, just as in JSON Pointer. INI values always remain strings, and literal backslashes are preserved. Empty pointers, pointers deeper than /section/key, malformed INI, and unmatched pointers are decoding errors.

Stored-value transforms run in this order:

provider or cache → encoding decode → structured extraction → as_path

This makes a Base64-encoded JSON document valid input when a declaration sets both encoding = "base64" (0.19+) and extract (0.19+). A provider-native ref.field is also resolved first, so a field whose contents are JSON can be selected further. Defaults and composed values are already logical and are not extracted.

Extracted secrets are read-only. set, delete, interactive prompting, generation, and import reject them rather than replacing or removing the containing document and its sibling values. Update the document through its owning system instead.

Secret References

The ref field names one externally managed secret by the store’s own coordinates, instead of SecretSpec’s {project}/{profile}/{key} convention. See Secret References for the concept, model, and examples; this section is the specification.

[profiles.production]DATABASE_URL = { description = "Postgres DSN", ref = { item = "db", field = "password" }, providers = ["prod_vault"] }INFRA_TOKEN  = { description = "Infra token", ref = { vault = "Production", item = "infra", field = "token" } }GITHUB_TOKEN = { description = "GitHub token", ref = { item = "GITHUB_PAT" }, providers = ["env"] }

ref is a table of provider-independent coordinates. Unknown keys are rejected at parse time. Only item is universal; it is the secret’s complete name in the store and replaces the whole convention path, including any folder_prefix or format string the provider is configured with (nothing is prepended). A coordinate a store has no equivalent for is rejected with an error naming it, never silently ignored.

Stores fall into two groups for field:

vault is the only container coordinate. For every store except 1Password the container is part of the provider URI, not the ref:

# The mount `kv2` comes from the URI; the ref names the path inside it.DB = { description = "DB", ref = { item = "myapp/config", field = "pw" }, providers = ["vault://vault.example.com:8200/kv2"] }
# 1Password: `vault` on the ref overrides the URI's default vault.TOKEN = { description = "Token", ref = { vault = "Production", item = "infra", field = "token" }, providers = ["onepassword://Private"] }

Which provider resolves a ref follows the ordinary provider resolution order; a ref composes with the providers fallback chain, and each provider is asked for the same coordinates.

Provider-scoped references

Use refs when one logical secret already has different native coordinates in different providers. Keys are leaf provider aliases; they are identity, not a URI lookup, so aliases that happen to resolve to the same URI remain distinct. An entry may name an import-only source alias that is absent from the secret’s ordinary providers route.

[providers]old = "onepassword://Legacy"new = { uri = "onepassword://Production", ref = { item = "{project}-{profile}", field = "{key}" } }local = "keyring://"
[profiles.production]API_KEY = { description = "API key", providers = ["new", "local"], refs = { old = { item = "legacy-api", field = "token" } } }

For each selected endpoint, address resolution is:

1. Legacy route-wide ref, when present (for compatibility).
2. The matching refs.<alias> entry.
3. The matching alias’s ref template.
4. The provider’s ordinary {project}/{profile}/{key} convention.

ref and refs cannot be combined on one effective secret. Every refs key must name a defined leaf alias; cached route aliases cannot own templates or be used as scoped-ref keys. A literal URI or bare provider name has no alias key, so only legacy ref or convention naming applies to it.

During profile inheritance, ref and refs (0.19+) form one setting rather than two independently inherited fields. The most specific profile entry that declares either form supplies the whole setting: an explicit refs replaces an inherited ref, and an explicit ref replaces inherited refs. If the profile entry declares neither, it inherits whichever form [profiles.default] uses.

How providers interpret the coordinates

A provider rejects coordinates it has no equivalent for, with an error naming the coordinate (for example, field on the env provider).

Writing through a ref

Writes are symmetric with reads: secretspec set and interactive check prompting write through the coordinates in place wherever the table above says writes are supported. Read-only stores fail with a clear error instead.

No string refs

ref is always a table. String and URI forms (ref = "op://vault/item/field", ref = "env://VAR", query-parameter URIs, and similar) are rejected, and the error spells out the exact table translation. For example, a pasted 1Password reference op://Production/infra/token translates to:

INFRA_TOKEN = { description = "Infra token", ref = { vault = "Production", item = "infra", field = "token" }, providers = ["onepassword://Production"] }

Provider URIs stay store addresses only: onepassword://Production names a vault, and item paths on provider URIs are errors.

Deduplication, auditing, and reporting

• Secrets sharing identical coordinates and store are fetched once.
• Audit log events carry a ref field with the coordinates.
• check --explain and check --json attribute ref secrets to the store URI they resolved from.

Prompt on missing during run

Use prompt = true when secretspec run should ask the operator after every configured provider has returned missing. Prompting is the value source; persistence remains a property of the selected provider.

With a writable provider, the answer is saved and reused by later runs. The write destination and writability are checked before the hidden prompt opens, just as they are for secretspec set. Use the null provider when the answer must exist only for one child invocation:

[profiles.default]DEPLOY_PASSWORD = { description = "One-time deployment password", required = true, prompt = true, providers = ["null"] }

Here null makes the operator the only possible value source and explicitly declines persistence, so the answer is injected into the child environment and discarded after it exits. It is not written to a provider or cache. The prompt uses the controlling terminal rather than the command’s stdin, so a pipe or redirected file remains available to the child:

$ printf 'deployment input\n' | secretspec run -- ./deploy? Enter value for DEPLOY_PASSWORD (profile: default):

Terminal window

Only run interprets prompt = true as a missing-value policy. get, export, SDK resolution, and value-free reports do not prompt. Interactive check retains its existing setup behavior instead: it offers to store any missing required secret, independently of prompt, and therefore cannot satisfy a null-backed declaration. A run without a controlling terminal fails before starting the child. Explicit set and import operations remain governed by the provider, not by prompt.

prompt = true is limited to individually required secrets and cannot be combined with default, enabled generate, extract, or composed. Profile overrides may set prompt = false to return to ordinary missing-value behavior.

Secret Generation

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 defaultsDB_PASSWORD = { description = "Database password", type = "password", generate = true }REQUEST_ID = { description = "Request ID prefix", type = "uuid", generate = true }
# Custom optionsAPI_TOKEN = { description = "API token", type = "hex", generate = { bytes = 32 } }SESSION_KEY = { description = "Session key", type = "base64", generate = { bytes = 64 } }
# Shell commandMONGO_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 }
# OpenPGP signing key (0.21+)RELEASE_KEY = { description = "Release signing key", type = "openpgp_private_key", generate = { user_id = "Release Bot <[email protected]>", capabilities = ["sign"] } }
# OpenSSH Ed25519 private key (0.21+)DEPLOY_KEY = { description = "Deployment SSH key", type = "ssh_private_key", generate = true }
# Type without generate: informational only, no auto-generationMANUAL_SECRET = { description = "Manually managed", type = "password" }

Generation Types

OpenPGP private-key generation

openpgp_private_key is generated entirely in Rust and does not invoke GnuPG. The default algorithm = "ed25519" creates an Ed25519 certification-only primary key plus separate Ed25519 signing and/or Curve25519 encryption subkeys. For compatibility with RSA-only consumers, algorithm = "rsa" uses RSA for the primary key and all requested subkeys. RSA defaults to 3072 bits; bits accepts 2048 through 8192 and is invalid with "ed25519".

Omitting capabilities selects both; the list must otherwise contain "sign", "encrypt", or both without duplicates. generate = true is invalid because every generated certificate requires an explicit user_id.

The ASCII-armored transferable secret key has no OpenPGP passphrase and no expiration. Store it with an encrypted provider when it needs protection at rest. Its public certificate and fingerprint can be derived after import by OpenPGP tooling; SecretSpec stores the secret key as one logical value.

SSH private-key generation

ssh_private_key is generated entirely in Rust. generate = true creates an unencrypted Ed25519 OpenSSH private key. Select algorithm = "rsa" for compatibility; RSA defaults to 3072 bits and accepts 2048 through 8192. bits is invalid with Ed25519. An optional comment is embedded in the key and must not contain control characters.

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)
• With providers = ["null"] (0.19+), a fresh generated value is returned only for the current resolution and is not written to provider storage
• 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)
• type = "openpgp_private_key" (0.21+) requires generate.user_id; omitted algorithm and capabilities default to Ed25519/Curve25519 and both signing and encryption, respectively
• type = "ssh_private_key" (0.21+) defaults to Ed25519; RSA generation is available with generate = { algorithm = "rsa", bits = 4096 }
• The value-free preflights — check --json / check --explain and the SDKs’ report/no-values resolutions — never mint a value. Since SecretSpec 0.20 a required generatable secret that no provider holds is reported as missing_required there (and exits non-zero) until a check or run provisions it; an optional one, or one stored in a provider that never retains generated values such as null, is reported as will generate

Profile Inheritance

• Non-default profiles inherit from [profiles.default] when it exists; profiles.\<name\>.defaults.inherit = false makes a profile standalone in SecretSpec 0.19+
• Profile-specific values override default values
• ref and refs (0.19+) are alternative forms of one setting: declaring either in a profile replaces the form inherited from [profiles.default], while declaring neither inherits it
• Use the extends field in [project] to inherit from other secretspec.toml files

Last updated Oct 08, 2026