sonny credentials is how you inspect and manage the credential sources Sonny resolves API keys from. The command name is plural — sonny credentials. There is no sonny credential command.

The concepts behind all of this — the resolution chain, the OS credential broker, and the legacy-credential migration — are on Credentials and Providers . This page is the command reference.

Usage:
  sonny credentials [command]

Available Commands:
  resolve        Print the selected source kind and location for a source id
  migrate-status Report where every legacy credential lives and what has converged
  retire-legacy  Remove a converged legacy credential copy
  delete         Remove a credential source or provider from the credential store

<div class="callout-title">
  <wa-icon name="circle-info" aria-hidden="true"></wa-icon>
  <span>Note</span>
</div>
Run sonny credentials --help to see the current subcommand list for your version. There is deliberately no --add, --list or --rotate flag: secrets are not meant to be typed onto a command line, where they land in shell history and in the process table. Add and rotate credentials through the TUI’s /setup flow or the Settings UI, or by writing a credential file with mode 0600.

Subcommands

SubcommandWhat it does
sonny credentials resolve <source id>Prints the selected source kind and location for one credential source — the provider’s own entry point when it has one, otherwise the default. This is how you find out which of the five sources actually won, without guessing.
sonny credentials migrate-statusReports where every legacy credential lives, per provider: provider config, auth store, credential broker, and whether each pair has converged. Optional --json.
sonny credentials retire-legacy <provider>Removes a legacy copy only after it has converged. Takes --force to retire immediately, bypassing the confirmation window.
sonny credentials delete <source or provider id>Removes what Settings’ “Remove stored credential” writes — the stored credential for that source or provider. Environment variables, .env files, and files you point at with SONNY_CREDENTIAL_FILE live outside the store and are not touched.

The resolution chain

Sonny resolves a credential source by checking each of these in order and using the first one found:

  1. Environment variables — e.g. ANTHROPIC_API_KEY.
  2. Credential files — ~/.config/sonny/credentials.json (user scope) or .sonny/credentials.json (project scope).
  3. External credential commands — credential_process, gcloud auth print-access-token, aws eks get-token.
  4. File-backed credentials — OAuth token files and Azure CLI token files.
  5. OAuth / SSO — interactive and headless login flows.

Use resolve to see which one was selected:

sonny credentials resolve openai
# kind=env location=ANTHROPIC_API_KEY

sonny credentials resolve anthropic
# kind=file location=~/.config/sonny/credentials.json

The output names the source and nothing secret: a key never reaches stdout.

Migration and the credential broker

Long-lived API keys are migrating from plain-text credentials.json into the operating-system credential broker. Both stores are live during the migration, so a machine can hold two copies of the same credential and drift.

# Where is each credential, and have the copies converged?
sonny credentials migrate-status
sonny credentials migrate-status --json

# Once converged, drop the legacy copy.
sonny credentials retire-legacy openai

Retirement is staged on purpose. migrate-status tells you whether a provider is ready; retire-legacy refuses to delete a copy that has not converged, because that would delete the only working credential. Pass --force only when you have confirmed the broker copy is the one you want to keep.

Provider configuration

Provider endpoints — not secrets — are configured with sonny config provider :

sonny config provider add --provider openai --endpoint https://api.openai.com/v1
sonny config provider remove --provider openai

Environment variables

VariablePurpose
ANTHROPIC_API_KEYAnthropic credentials
OPENAI_API_KEYOpenAI credentials
GOOGLE_API_KEYGoogle/Gemini credentials
GITHUB_TOKENGitHub MCP server credentials
GITLAB_TOKENGitLab MCP server credentials
SONNY_CREDENTIAL_FILEPoint at a file-backed credential source

Security notes

  • Credential files should be chmod 600.
  • Project-scoped credentials can differ from user-scoped ones — check both when behavior is unexpected, and confirm with resolve.
  • The TUI Settings → Credentials screen and sonny credentials resolve report the same information: source, kind, provider, masked key.
  • Deleting a credential in Settings removes it from Sonny’s store but does not revoke it at the provider. Rotate or revoke the key with the provider too.

See also