Credentials

Stella resolves an API key for the selected provider through a well-defined chain, and can persist keys in a permission-restricted file so you're only prompted once.

The credential chain

For the selected provider, the key is resolved in this order — first hit wins:

1. --api-key flag — highest precedence. Requires an explicit --model provider/... (a bare key is ambiguous about which provider it belongs to).
2. Provider env var — e.g. ANTHROPIC_API_KEY, plus aliases like GOOGLE_API_KEY for Gemini. A providers.<id>.api_key_env in settings.json renames the primary variable: the named variable becomes the one checked first and the provider's original env var demotes to an alias — handy for team key rotation (MY_TEAM_ZAI_KEY) without touching anyone's shell profile.
3. settings.json — providers.<id>.api_key (an empty string is treated as unset; see settings.json).
4. ~/.config/stella/credentials.toml — the stored-keys file below.
5. Interactive prompt — on a TTY, when you've named a provider with --model provider/model_id (e.g. --model anthropic/claude-fable-5), Stella prompts for the key and saves it to credentials.toml, so you are only asked once. A bare invocation with no --model uses auto-detection, which does not prompt — it errors with guidance to name a provider instead.

credentials.toml

Keys can be stored in ~/.config/stella/credentials.toml. It is a flat table keyed by provider id:

[credentials]
zai = "sk-..."
anthropic = "sk-ant-..."
openai = "sk-..."
# config-defined provider ids work too — key matches your settings.json entry
together = "..."

• The file is written with owner-only (0600) permissions — it holds secrets in plaintext, the same threat model as ~/.ssh/config.
• Writes are atomic (a temp file is renamed into place), so a reader never sees a half-written file.
• When you enter a key at the interactive prompt, Stella writes it here automatically.

Which key is active?

stella config

This prints the provider, model, and a redacted preview of the active key (a few leading and trailing characters, middle elided) so you can confirm which key is in use without printing the secret.

Cloud provider credentials

Some providers need more than a single key:

• Vertex AI — VERTEX_ACCESS_TOKEN plus VERTEX_PROJECT_ID (or GOOGLE_CLOUD_PROJECT), and optionally VERTEX_LOCATION.
• Amazon Bedrock — AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, plus optional AWS_SESSION_TOKEN and AWS_REGION.

These are read from the environment. See Providers & models for the full matrix.