Credential storage

5 min readFor operatorsUpdated 2026-05-23

Craik separates credential profiles from credential material. Provider profiles live in <CRAIK_HOME>/auth-profiles.json; captured API keys resolve through the credential backend named by the profile's keyring-ref metadata.

Backends

Backend

Platform

Notes

macos-keychain

macOS

Used when the optional Python keyring backend is installed and available. Otherwise Craik reports the backend as unavailable and can fall back to file storage when explicitly configured.

windows-credential-manager

Windows

Used through the optional Python keyring backend when available. Windows ACL handling is delegated to the platform credential manager.

secret-service

Linux

Depends on the local Secret Service session and keyring backend availability. Headless Linux deployments should prefer explicit secret references or configure a supported keyring service.

file

fallback

Stores plaintext credential values under Craik home with owner-only POSIX permissions. Use only when the operator accepts the plaintext-at-rest tradeoff.

Inspect the current backend without printing secret material:

craik auth storage status

Capture-and-cache flow

craik auth login <provider> prompts for a provider API key, validates that the captured value is usable for a profile, stores it through the credential backend, and writes a redacted keyring-ref profile. Status and dashboard/TUI views show the backend and health state but never the credential value.

craik auth login openai --json
craik auth status

craik auth logout <provider> removes the profile and deletes the cached credential reference when the profile uses keyring-ref.

Migration

Use the one-time migration helper for older env-var profiles:

craik auth migrate-from-env --dry-run
craik auth migrate-from-env --apply --yes

The helper reads each configured env var only after consent, copies the resolved value into the credential backend, converts the profile to keyring-ref, and leaves the original environment variable untouched. Running it again skips already migrated profiles.