spade secret

The spade secret command manages local secrets — database connection strings, API keys, and other sensitive values — used by pipeline blocks. Values are stored in the operating-system keychain and injected into blocks at run time by spade run, so they never appear in a pipeline file, logs, or on disk.

A pipeline block references a secret by name in its secrets mapping. The block author reads it with get_secret("<logical-name>"); the pipeline binds that logical name to one of your stored secrets:

- id: 019cf4bc-2222-7000-0000-000000000000
  name: db.query
  args:
    query: "SELECT * FROM parcels"
  secrets:
    db: prod-postgres-dsn   # value is the NAME of a stored secret, never the secret

Usage🔗

spade secret set <name>     # store a value (prompted, or piped via stdin)
spade secret list           # list stored secret names
spade secret rm <name>      # remove a secret

Setting a secret🔗

The value is read from the terminal without echoing:

spade secret set prod-postgres-dsn
Enter secret value: ················
Stored secret "prod-postgres-dsn" in the OS keychain.

Or piped from standard input, for scripting:

echo "$DATABASE_URL" | spade secret set prod-postgres-dsn

Storage🔗

Secrets are kept in the OS keychain:

spade secret list cannot ask the OS keychain to enumerate its entries, so the CLI separately maintains a small index of secret names (never values) under a reserved keychain key to back the list command.

Errors🔗

If a pipeline block references a secret that is not in the keychain, spade run fails with an actionable message naming the secret and how to set it:

resolving secrets for block db.query: secret "prod-postgres-dsn" (bound to "db")
is not in the local keychain; set it with `spade secret set prod-postgres-dsn`

Planned: cloud-backed secrets🔗

spade secret only manages the local OS keychain today. There is no --remote flag, and the CLI has no way to write to, list, or remove a cloud-side secret — set/list/rm all operate exclusively on the machine they run on.

A cloud secrets store (a KMS-backed backend used by cloud pipeline runs) is on the roadmap, along the lines described in spec/secrets.md: the same logical secret name would resolve to a local value for spade run and to a separate cloud-stored value for cloud runs, without editing the pipeline. Until that lands, cloud secrets (if any exist for your deployment) must be managed through whatever cloud-side tooling your deployment provides — not through spade secret.