fluid secrets

Manage secrets used by acquisition pipelines — Postgres passwords, Snowflake key-pair paths, Airbyte API tokens, etc. Lives under its own umbrella so it doesn't collide with fluid auth (cloud-provider auth) or fluid ai setup (LLM credentials).

Syntax

fluid secrets <subcommand> <secretRef> [options]

The secretRef here is a name you choose for the keychain entry, for example postgres.prod.password, airbyte.token or snowflake.keypair_path. It is not the secretRef URI a contract uses (env://PGPASSWORD, vault://...).

Subcommands

fluid secrets login

Store a secret. The value is read from stdin (when piped) or an interactive hidden prompt — never from a command-line flag, so it can't leak via ps or shell history.

fluid secrets login postgres.prod.password
# (prompts for value; input is hidden)

# Pipe the value from stdin (CI / scripted)
printf '%s' "$AIRBYTE_TOKEN" | fluid secrets login airbyte.token

cat /etc/keys/sf.p8 | fluid secrets login snowflake.keypair_path --expires-at 2027-01-01T00:00:00Z

fluid secrets verify

Probe the backend to confirm the secret exists and is reachable. Does not echo the value.

fluid secrets verify postgres.prod.password
fluid secrets verify postgres.prod.password --json

fluid secrets rotate

Replace a stored secret with a new value. The new value is read from stdin or an interactive hidden prompt — never from a flag. The result object's detail field reports rotated when a prior secret existed, or stored (no prior secret) when there wasn't one.

fluid secrets rotate postgres.prod.password
# (prompts for new value)

# Pipe the new value from stdin
printf '%s' "$NEW_TOKEN" | fluid secrets rotate airbyte.token --expires-at 2027-04-01T00:00:00Z

--json output

All three subcommands share one result shape under --json:

{
  "success": true,
  "ref": "postgres.prod.password",
  "backend": "keychain",
  "detail": "present",
  "expires_at": null
}

That is the shape verify returns for a stored secret.

• success: true when the operation completed; the process exit code mirrors this.
• backend: keychain (default) or memory (when FLUID_SECRETS_INMEMORY=1).
• detail: a short note. login leaves it null; verify says present or not found in backend; rotate says rotated or stored (no prior secret).
• expires_at: echoes --expires-at when one was passed; otherwise null.

Backends

You don't pick the backend on the command line; it's process-global per the env var.

How contracts consume secrets

A contract names a secret with a secretRef URI, <scheme>://<identifier>, on the field that needs it. For an acquisition source it sits in connection:

builds:
- id: ingest_orders
  pattern: acquisition
  properties:
    source:
      kind: postgres
      connection:
        host: "{{ env.PGHOST }}"
        database: orders
        user: ingest
        secretRef: env://PGPASSWORD
      mode: full_refresh
      streams: [public.orders]

The runner resolves the URI when the build runs. A literal password in the same connection block wins over secretRef, so a contract that fluid init --discover wrote, which carries the URI's password in connection.password, needs that line deleted when you add the secretRef. A password typed into a command-line URI also lands in shell history and in ps output; keep it out of the URI where you can. The schemes are:

Any other scheme fails with the list of supported ones. {{ env.VAR }} is a different mechanism: it substitutes an environment variable into a string field of the contract. When fluid apply or fluid publish resolves a contract, a placeholder whose name looks like a credential (..._PASSWORD, ..._TOKEN, ..._SECRET, ..._API_KEY) is left unresolved, so use secretRef for credentials. No ${SECRET:...} placeholder exists.

Use env:// in CI, where the variable comes from your CI system's secret store, and vault://, aws://, gcp:// or azure:// where a secrets manager holds the value. The keychain is not among the schemes, so fluid secrets login does not feed a build. Its entries are for the CLI's own fluid secrets verify and rotate.

Exit codes

See also

• Source-Aligned Acquisition — why pipelines need secrets
• Credential Resolver: how the CLI stores and reads catalog credentials
• Typed CLI Errors: SecretResolutionError