id          = "secretspec"
name        = "SecretSpec"
homepage    = "https://secretspec.dev/"
description = "A declarative interface for every secret provider."
executables      = ["secretspec"]

[dotfiles]

# The official configuration reference names ~/.config/secretspec/config.toml
# as the per-user defaults/aliases file. It follows the XDG config directory;
# the project-level secretspec.toml is deliberately omitted because it lives
# beside each project rather than under the user's home.
# https://secretspec.dev/reference/configuration/
paths  = ["[configHome]/secretspec/config.toml"]
secret = []

[commands]
format = 1
label = "SecretSpec"
description = "Check, read and run commands with secrets declared in secretspec.toml. Set, import, init and provider configuration subcommands are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.subcommand]]
path = ["check"]
label = "Check secrets"
description = "Verify that every declared secret resolves, without printing values."

[[commands.subcommand.source]]
id = "cli"
kind = "manual"
url = "https://secretspec.dev/reference/cli/"
revision = "2026-10-27"
evidence = """
secretspec check [OPTIONS]
-p, --provider <PROVIDER> - Provider backend to use
-P, --profile <PROFILE> - Profile to use
-n, --no-prompt - Don't prompt for missing secrets (exit with error if any are missing)
--json - Print a value-free resolution report as JSON instead of prompting
--explain - Print a value-free, human-readable resolution trace instead of prompting
-f, --file <FILE>Path to secretspec.toml (default: auto-detect). Env: SECRETSPEC_FILE
"""

[[commands.subcommand.field]]
id = "profile"
label = "Profile"
type = "string"
option = ["--profile", "-P"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "provider"
label = "Provider"
description = "Provider URI or name, for example env or dotenv://.env."
type = "string"
option = ["--provider", "-p"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "file"
label = "secretspec.toml path"
type = "path"
path = { kind = "file", role = "input" }
option = ["--file", "-f"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "no_prompt"
label = "Do not prompt"
type = "boolean"
option = ["--no-prompt", "-n"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "json"
label = "JSON report"
type = "boolean"
option = ["--json"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "explain"
label = "Explain resolution"
type = "boolean"
option = ["--explain"]
sources = ["cli"]

[[commands.subcommand.task]]
id = "check"
label = "Check a profile"
fields = ["profile"]
required = []

[[commands.subcommand.task]]
id = "explain"
label = "Explain resolution"
fields = ["profile"]
required = []
set = { explain = [true] }

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["profile", "provider", "no_prompt", "explain", "json"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["file"]

[[commands.subcommand]]
path = ["get"]
label = "Get one secret"
description = "Print the value of a single secret to the terminal."

[[commands.subcommand.source]]
id = "cli"
kind = "manual"
url = "https://secretspec.dev/reference/cli/"
revision = "2026-10-27"
evidence = """
secretspec get [OPTIONS] <NAME>
-p, --provider <PROVIDER> - Provider backend to use
-P, --profile <PROFILE> - Profile to use
$ secretspec get DATABASE_URL --profile production
-f, --file <FILE>Path to secretspec.toml (default: auto-detect). Env: SECRETSPEC_FILE
"""

[[commands.subcommand.field]]
id = "name"
label = "Secret name"
type = "string"
position = 0
min = 1
sources = ["cli"]

[[commands.subcommand.field]]
id = "profile"
label = "Profile"
type = "string"
option = ["--profile", "-P"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "provider"
label = "Provider"
type = "string"
option = ["--provider", "-p"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "file"
label = "secretspec.toml path"
type = "path"
path = { kind = "file", role = "input" }
option = ["--file", "-f"]
sources = ["cli"]

[[commands.subcommand.task]]
id = "get"
label = "Get a secret"
fields = ["name", "profile"]
required = ["name"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["name", "profile", "provider", "file"]

[[commands.subcommand]]
path = ["run"]
label = "Run with secrets"
description = "Run a command with the declared secrets injected as environment variables."

[[commands.subcommand.source]]
id = "cli"
kind = "manual"
url = "https://secretspec.dev/reference/cli/"
revision = "2026-10-27"
evidence = """
secretspec run [OPTIONS] -- <COMMAND>
$ secretspec run --reason "Deploying web frontend" -- ./deploy.sh
--reason <REASON>Reason for accessing secrets, recorded by providers that support audit logging (e.g. Proton Pass agent sessions).
-p, --provider <PROVIDER> - Provider backend to use
-P, --profile <PROFILE> - Profile to use
-f, --file <FILE>Path to secretspec.toml (default: auto-detect). Env: SECRETSPEC_FILE
"""

[[commands.subcommand.field]]
id = "profile"
label = "Profile"
type = "string"
option = ["--profile", "-P"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "provider"
label = "Provider"
type = "string"
option = ["--provider", "-p"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "reason"
label = "Access reason"
description = "Recorded by providers that support audit logging."
type = "string"
option = ["--reason"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "file"
label = "secretspec.toml path"
type = "path"
path = { kind = "file", role = "input" }
option = ["--file", "-f"]
sources = ["cli"]

[[commands.subcommand.field]]
id = "command"
label = "Command"
description = "Command and arguments to run, placed after --."
type = "string"
position = 0
multiple = true
min = 1
sources = ["cli"]

[[commands.subcommand.task]]
id = "run"
label = "Run a command"
fields = ["profile", "reason", "command"]
required = ["command"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["profile", "provider", "reason", "command"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["file"]