Credentials

Profile credentials are write-only Vault overrides. The permanent default profile uses the user credential namespace; every other profile gets its own owner prefix.

Declared extension environment names use instance/profile-owned bindings through extension secrets, as described below.

Set and inspect a provider credentialCopy Anchor Link

Pass the value through standard input so it does not enter shell history:

printf '%s' "$ANTHROPIC_API_KEY" |
  compozy --profile marketing secret set providers/claude/api_key --value-stdin -o json

compozy --profile marketing provider inspect claude -o json

secret set returns only ref, profile, and status. provider inspect shows the effective credential source and fallback chain without returning the credential value.

--from-env is available only for the default profile. A process environment is shared by every profile, so a non-default profile rejects it with profile_secret_env_forbidden and directs you to --value-stdin.

Bind an extension credentialCopy Anchor Link

Use the dedicated extension-secret command to store a value and bind it to an environment name declared by the extension. For example, the bundled pull request provider declares GITHUB_TOKEN:

printf '%s' "$GITHUB_TOKEN" |
  compozy --profile marketing extension secrets set forge-github \
    --env GITHUB_TOKEN --value-stdin -o json

compozy --profile marketing extension secrets list forge-github -o json

The list reports declared names, bound names and stale status without returning secret values or Vault refs. Add --workspace <workspace> when targeting a workspace instance, and use the same profile and workspace selection for inspection and removal.

secret set extensions/<extension>/<key> stores a generic Vault value; it does not create this binding. Its vault:profiles/<name>/extensions/... reference is not accepted by extension secrets bind, which requires an instance/profile-owned vault:extensions/... reference. Prefer extension secrets set so the runtime creates the appropriate reference and binding together. See Extension Secret Bindings for namespace and fallback details.

Remove the binding through the same surface:

compozy --profile marketing extension secrets unset forge-github --env GITHUB_TOKEN -o json

Remove a provider overrideCopy Anchor Link

compozy --profile marketing secret rm providers/claude/api_key -o json

When the profile owns work, interactive output warns that future runs will fall back to the user credential. Structured or non-interactive callers must acknowledge that transition with --yes:

compozy --profile marketing secret rm providers/claude/api_key --yes -o json

Removal never deletes the user credential. Read provider inspect again to confirm the effective source before starting new work.

Profile lifecycleCopy Anchor Link

Profile rename moves owned Vault refs to the new owner prefix as part of the rename plan. Profile deletion includes credential overrides in its impact plan. Complete or recover the profile operation instead of editing Vault paths directly.

Agent-managed surfacesCopy Anchor Link

The same credential metadata and profile ownership are available through HTTP and UDS Vault and provider-status endpoints. Secret values remain write-only on every surface. Agents should resolve the live descriptor, write the exact owner-qualified ref, then verify the redacted provider source.

RelatedCopy Anchor Link

Create your first profile walks through setting an override in context. Profile files lists the rest of what a profile owns on disk, and Extension secrets covers the extension side of the same binding rule.