stella auth
Store, list, and remove your BYOK provider keys in credentials.toml, the file where your API keys live.
stella auth manages the BYOK provider keys stored in ~/.stella/credentials.toml. It's the command that writes the credentials file the credential chain reads from: a small, deliberate tool for a handful of keys, not a configuration language. It never prints a secret value, and it doesn't need a model API key of its own.
Synopsis
stella auth set <provider> [--key <key> | --stdin] [--field <NAME=VALUE>]...
stella auth remove <provider>
stella auth listWhat it does
A key stored here stays saved across sessions and shells, so you don't have to re-export an environment variable every time. It sits near the end of the credential chain: a key resolved from --api-key, an environment variable, or settings.json still wins over it. Run stella config or stella models to see which source actually wins for a given provider.
<provider> is a provider id: a built-in one such as zai, anthropic, or openai, or a custom provider id you defined in settings.json.
stella auth set <provider>
Store or replace a provider's key. With no flag, stella shows an interactive masked prompt. This is the recommended way, since nothing lands in your shell history.
--key <key>Pass the key inline. This is visible in shell history and in ps output — prefer
--stdin or the interactive prompt. Cannot be combined with --stdin.
--stdinRead the key from stdin, as one trimmed line. Good for scripts and secret managers.
--field <NAME=VALUE>Store one extra value a provider needs beyond its key. Can be repeated. Only
Bedrock needs any today. Visible in shell history and in ps, like --key —
leave it off for a masked prompt covering each one.
# Interactive, masked (recommended)
stella auth set anthropic
# From a secret manager, nothing in shell history
printf '%s' "$MY_KEY" | stella auth set zai --stdinMost providers need only one key, so set stores it and stops. Bedrock needs more: AWS_SECRET_ACCESS_KEY,
AWS_SESSION_TOKEN, and AWS_REGION alongside the access-key id. Run stella auth set bedrock with no flags, and stella asks for each one in turn. Secrets are masked;
AWS_REGION is not, because it's a routing setting, not a secret. Leaving an answer blank keeps the existing value.
# Interactive: prompts for the key, then for each extra field
stella auth set bedrock
# Scripted — these land in shell history, exactly as --key does
stella auth set bedrock --key "$AWS_ACCESS_KEY_ID" \
--field AWS_SECRET_ACCESS_KEY="$SECRET" \
--field AWS_REGION=us-east-1--key and --stdin skip the extra-field prompts entirely, since a script that pipes in a key
must never wait on a question. So a scripted stella auth set bedrock --key … with no
--field stores a credential that cannot sign a request. It resolves fine at
stella models and then fails at the first real call with a signing
error naming a variable you thought you had already set. set warns when it stores a
Bedrock key with no AWS_SECRET_ACCESS_KEY beside it — run it again without --key/--stdin,
or pass the field.
stella auth remove <provider>
Delete a provider's stored key.
stella auth remove openaistella auth list
List every provider with a key in credentials.toml, each with a masked preview and where it came from. Extra values stored with --field are listed by name only, never by value, the same rule as the key itself. They're shown at all because a Bedrock row missing its AWS_SECRET_ACCESS_KEY would otherwise look identical to a working one.
stella auth listPrefer the interactive prompt or --stdin over --key. A key passed with --key is visible in your shell history and in ps output. See Credentials for the full resolution order.