opencues set-key <provider> <key> stores an API key where every OpenCues host can find it: ~/.cues/.env, written with chmod 600 permissions. It exists so you don't have to manage export lines in your shell rc, and so keys work identically whatever shell each host happens to launch from.
What it accepts
Both LLM providers and the non-LLM service key the shipped blanks use:
- LLM providers:
cerebras,groq,gemini,anthropic,openai,openrouter,opencode-zen. - Service keys:
finnhub, the free key the stocks blank needs for live quotes.
So a typical setup is two commands: opencues set-key cerebras csk-... for the model and opencues set-key finnhub xxx if you want stock prices. Setting keys for both Cerebras and Groq is worth the extra minute: with both present, OpenCues fails over automatically between them on rate limits and server errors, and since both serve the same gpt-oss-120b weights there's no quality shift when it does.
Why a file instead of an environment variable
Environment variables work too (CEREBRAS_API_KEY, GROQ_API_KEY, and so on), and hosts read both process.env and ~/.cues/.env at boot. The trouble with the env-var route is persistence: an export in a one-off terminal doesn't survive, so it has to live in ~/.bashrc or its equivalent, per shell, per machine. The install docs' own framing is that set-key is the shell-agnostic alternative: one write, and every host launched any way picks it up. The file is created with owner-only permissions (chmod 600).
Verifying a key actually works
The companion command is opencues check-keys: it hits each configured provider's lightest endpoint and reports which keys are live, so a typo'd or revoked key shows up as a named failure instead of as blanks mysteriously not resolving. If a key-dependent feature is silently dead, run opencues doctor first (missing keys are one of the things it flags), then check-keys to test the key itself.
Where the key goes, and doesn't
The key stays on your machine. There is no OpenCues account and no middleman service: hosts read the key at startup and send requests directly to the provider you chose, on your key. A missing key fails visibly rather than mysteriously: the stocks blank simply doesn't register without its Finnhub key, and opencues doctor lists missing provider keys as named findings with the set-key fix attached.
Where it fits in setup
set-key is one of the five commands the CLI reference singles out as the ones you'll actually use, alongside install, run, doctor, and update. For most people it's a once-per-machine action: store a provider key, optionally store a Finnhub key and a Groq fallback key, and never think about it again. When you switch providers later, it's one more set-key plus flipping the llm-provider scalar.
Related: CLI reference · LLM providers · Rate limits and failover · The missing key hint · GitHub repo