Get and store an API key

icuvisor needs an intervals.icu API key to read your training data. The key is a credential, not a chat prompt: do not paste it into Claude, ChatGPT, or any MCP client JSON.

1. Create the key in intervals.icu

  1. Open https://intervals.icu/settings.
  2. Create or copy an API key.
  3. Keep the browser tab open until setup has stored the key.

2. Store it with icuvisor setup

Run setup from your installed binary:

/Applications/icuvisor.app/Contents/MacOS/icuvisor setup

If you built from source, run:

./bin/icuvisor setup

Setup asks for the API key with masked input, verifies it with intervals.icu, stores it in the OS keychain, autodetects your athlete ID/timezone, and writes only non-secret config fields.

Useful setup flags are documented in the CLI reference:

  • --config /path/to/config.json writes a specific non-secret config file.
  • --force overwrites an existing config file without the overwrite prompt.
  • --offline skips intervals.icu verification when you are offline and accepts manual athlete ID/timezone prompts.

3. Configure your MCP client with non-secrets only

MCP client JSON should contain only values such as INTERVALS_ICU_ATHLETE_ID, ICUVISOR_TIMEZONE, ICUVISOR_TRANSPORT, or a --config path. The API key stays in the OS keychain.

Manual keychain storage

Manual storage is useful for advanced or headless setup, but icuvisor setup is the recommended path.

macOS Keychain

Use Keychain Access, or run:

security add-generic-password -U \
  -s icuvisor \
  -a intervals-icu-api-key \
  -w 'YOUR_INTERVALS_ICU_API_KEY'

Windows Credential Manager

Open Credential Manager and add a Windows credential with:

  • Internet/network address: icuvisor:intervals-icu-api-key
  • User name: intervals-icu-api-key
  • Password: your intervals.icu API key

CLI equivalent:

cmdkey /add:icuvisor:intervals-icu-api-key /user:intervals-icu-api-key /pass:YOUR_INTERVALS_ICU_API_KEY

Linux libsecret

On desktop Linux with Secret Service support, use Passwords and Keys, KWallet, or:

secret-tool store --label='icuvisor intervals.icu API key' service icuvisor username intervals-icu-api-key
# Paste the intervals.icu API key when prompted.

If secret-tool is missing, install your distribution’s libsecret package. Headless systems without a keychain can use INTERVALS_ICU_API_KEY as a deliberate fallback; remember that process environments are easier to leak through shell history, process listings, logs, and service files.

Credential precedence

When icuvisor starts, the API key comes from the highest available source:

  1. Process environment INTERVALS_ICU_API_KEY.
  2. OS keychain service icuvisor, account intervals-icu-api-key.
  3. Legacy plaintext .env or JSON config fallback.

Plaintext keys emit a warning and should not be committed or backed up.