Connect a provider

Save a provider key

Get an API key from your provider, then save it. Codewhale asks for the key and does not echo it. DeepSeek is the default provider, so it is the example here.

codewhale auth set --provider deepseek
codewhale auth status --provider deepseek

auth status names the source in use — config file, secret store, or environment variable — and shows only the last four characters. In a script, pipe the key in with --api-key-stdin instead of typing it.

You can also connect from inside Codewhale: press F3 (or type /provider), choose a provider, paste the key, then pick a model.

Note: In v0.10.0, auth set --provider deepseek also switches your default model to DeepSeek Pro. Run /model if you want the faster, cheaper model back. Connecting through F3 keeps your current model.

Know which key is used

When a key is set in more than one place, the first match in this order wins:

1. --api-key on the command line, for one run.
2. api_key in ~/.codewhale/config.toml.
3. The secret store written by codewhale auth set.
4. The provider's environment variable, such as DEEPSEEK_API_KEY.

Exporting a new environment variable therefore does not replace a key you saved earlier. If a rotated key keeps failing, run auth status to see which source is active, then save the new key or clear the stored one:

codewhale auth clear --provider deepseek

On Linux the secret store is a private file (mode 0600) under ~/.codewhale/secrets/, not an OS keyring. codewhale doctor --probe-api makes one test call to confirm that the key and the network both work.

Use another provider or a local model

codewhale auth list shows every provider Codewhale knows and whether each one has a key. The pattern is the same for all of them: codewhale auth set --provider <name>, or that provider's environment variable.

Local runners — Ollama, vLLM, and SGLang — need no key by default, and your prompts stay on your machine. Start the runner, then choose it:

codewhale auth list
codewhale --provider ollama --model <model-tag>

The models page lists providers, local setups, and how to switch models mid-session.

Sign in to a Codewhale account (optional)

A provider key and a Codewhale account are different things. The account is for account features only, such as cloud agents and continuing a session from the web app. Installing Codewhale and working locally never need one.

codewhale login

Sign in through your browser with a one-time code.

codewhale account status

Show which account this profile is signed in to.

codewhale account logout

Remove this profile's session.

codewhale account keys list

List provider keys saved in your account. Values are never shown.

codewhale login does not accept provider keys; those always go through codewhale auth set. The session is kept in your operating system's credential manager when one is available, and in the private Codewhale secrets file otherwise — for example over SSH or in a container.

Next