CLI · Secrets and vault

Project YAML never contains secret values. Anywhere a credential is needed — connection strings, REST auth headers, database passwords — the YAML carries a vault reference:

auth:
  kind: bearer
  value_ref: "${vault:crm/api:token}"

The ref has three parts: the literal vault scheme, a secret id (crm/api), and a key within that secret (token). Refs are resolved at runtime by the project’s configured vault provider — set with kiri project patch --op set_vault_provider and matched by the vault.prefix in kiri.yml (default KIRIMANA). On a wired Databricks target, the vault-scope wiring is smoke-tested by kiri databricks setup and probed by kiri databricks health (platform-ops page).

kiri vault set

Store a secret under <id>:<key> in the project vault.

Usage: kiri vault set [OPTIONS] SECRET_ID

Flag	Description	Default
--key, -k	Which key inside the secret to set (e.g. password, config) — required
--from-env	Read the value from this env var instead of prompting. Useful in CI — the source env var is read and deleted from the process after writing.
--project	Project root (where the vault’s .env lives)
--prefix	Vault prefix; matches vault.prefix in kiri.yml	KIRIMANA
--force	Overwrite an existing entry without asking	off

Interactive use prompts for the value so it never lands in shell history:

kiri vault set crm/api --key token

CI use passes through an environment variable:

CRM_TOKEN=… kiri vault set crm/api --key token --from-env CRM_TOKEN

The secret id is the middle segment of every ${vault:<id>:<key>} ref in project YAML — setting crm/api:token satisfies every ref that points at it.

kiri vault list

Show every vault-shaped entry visible to the project.

Usage: kiri vault list [OPTIONS]

--prefix (default KIRIMANA) selects the vault namespace; --project points at the project root. Values are not printed — the listing shows which <id>:<key> pairs exist, so you can diff it against the refs your YAML declares.

Rotation

Rotation is a re-set: write the new value over the same <id>:<key> with --force, and every ref resolves to the new value on the next run — no YAML changes, no redeploys.

kiri vault set crm/api --key token --force

Because refs are indirection, rotating a credential never touches contracts, sources, or targets. For platform-side credentials (the Databricks service-principal token), rotate at the platform and re-run kiri databricks health to confirm the wiring.

Where refs are accepted

Vault refs resolve anywhere project YAML takes a credential, including:

• kiri discover --conn connection strings
• kiri source introspect auth flags: --auth-value-ref, --auth-username-ref, --auth-password-ref, --db-username-ref, --db-password-ref
• REST source definitions (--header / --query-param values)
• Target profiles in kiri.yml

Two hygiene rules the CLI enforces or expects:

1. Pass paths, not contents. Verbs that take connector configuration accept a file path and treat the file as secret — never inline JSON with credentials on the command line.
2. No secrets in YAML commits. kiri source validate and kiri contract lint operate on the assumption that YAML carries refs only; a raw credential in YAML is a review-blocking finding.