# How to Configure API Keys for claude-video Using ~/.config/watch/.env

> Configure API keys for claude-video easily by adding your GROQ or OPENAI key to the ~/.config/watch/.env file. The setup script handles initialization automatically.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-07-25

---

**Configure API keys for claude-video by placing your `GROQ_API_KEY` or `OPENAI_API_KEY` in the `~/.config/watch/.env` file, which the setup script initializes automatically on first run.**

The `bradautomates/claude-video` repository requires Whisper API credentials to process video transcription. To configure API keys for claude-video securely without exposing secrets in your repository, you must use the dedicated environment file located at `~/.config/watch/.env`. This approach keeps sensitive credentials outside version control while allowing the transcription pipeline in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) to authenticate with Groq or OpenAI.

## Configuration File Location and Format

The application expects a specific file path and format for environment variables.

### The ~/.config/watch/.env Path

`claude-video` reads Whisper credentials exclusively from the hidden environment file at `~/.config/watch/.env`. The setup script at [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) creates this file automatically during the first run (lines 38-55), scaffolding a placeholder template that you must edit with actual key values. If the file does not exist, the installer generates the directory structure and a template with empty variables.

### Required Environment Variables

The file uses standard `KEY=VALUE` format—one key per line, with no trailing comments unless the value is quoted. The transcription logic in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) recognizes two supported keys:

- **`GROQ_API_KEY`**: Preferred Whisper-large-v3 key (cheaper and faster). Obtain from [console.groq.com/keys](https://console.groq.com/keys).
- **`OPENAI_API_KEY`**: Fallback Whisper key from [platform.openai.com/api-keys](https://platform.openai.com/api-keys).

When both keys are present, the Groq key takes precedence according to the internal resolution logic.

## How the Setup Script Manages the Configuration

The [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) file handles initial configuration and validation through several specific functions.

### Automatic File Creation

When you run the setup script for the first time, it executes the template creation logic in lines 38-55 to generate `~/.config/watch/.env` with placeholder content. This ensures the correct file structure exists before you insert credentials.

### API Key Validation

The script validates configuration using `_have_api_key()` (lines 16-21), which checks whether either `GROQ_API_KEY` or `OPENAI_API_KEY` exists in the file. If a valid key is detected, the installer writes a `SETUP_COMPLETE=true` marker to the same `.env` file (lines 42-58), signaling that the initialization phase is finished.

### Low-Level Key Reading

For specific key retrieval, the setup script implements `_read_env_key()` in lines 92-110. This utility extracts individual values from the configuration file without loading the entire environment, providing precise control during the installation checks.

## How claude-video Loads the API Keys

Once configured, the application reads the credentials through dedicated configuration modules.

### Environment File Parsing

The [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) module contains `read_env_file()` (lines 17-45), which loads the `~/.config/watch/.env` file and merges its values with the current environment. This function returns the chosen `watch_detail` setting and the path to the configuration file, making credentials available to the transcription pipeline.

### Transcription Backend Selection

The [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) implementation selects the Whisper backend based on available keys. If `GROQ_API_KEY` is present, it routes requests to Groq's Whisper-large-v3 endpoint; otherwise, it falls back to `OPENAI_API_KEY` for OpenAI's Whisper service. This selection happens automatically when the main entry point in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) initializes the transcription process.

## Step-by-Step Configuration Guide

Follow these steps to configure your API keys correctly.

### 1. Run the Setup Script

Execute the setup script to create the configuration directory and template file:

```bash
python3 -m skills.watch.scripts.setup

```

On first run, the output confirms creation:

```text
[setup] created config: /home/youruser/.config/watch/.env

```

This invokes the file creation logic in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) lines 38-55.

### 2. Add Your API Key

Edit the generated file with any text editor to insert your actual key:

```bash
nano ~/.config/watch/.env

```

Replace the placeholder with your Groq key (preferred) or OpenAI key:

```text

# ~/.config/watch/.env

GROQ_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# or, if using OpenAI:

# OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

```

Save the file. The `KEY=VALUE` format requires no quotes for standard alphanumeric keys.

### 3. Verify the Configuration

Confirm that the setup script recognizes your credentials:

```bash
python3 -m skills.watch.scripts.setup --check

```

This command returns exit code 0 if `_have_api_key()` detects a valid key and all binaries are installed. Alternatively, verify programmatically:

```python
from skills.watch.scripts.config import get_config

cfg = get_config()
print(cfg["config_file"])  # Should print: ~/.config/watch/.env

```

If configured correctly, running `/watch` will automatically pick up the credential and enable Whisper transcription.

## Summary

- **Store credentials** in `~/.config/watch/.env` using `GROQ_API_KEY` or `OPENAI_API_KEY` format.
- **Automatic setup**: Run `python3 -m skills.watch.scripts.setup` to create the file via [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) lines 38-55.
- **Validation**: The setup script checks for keys using `_have_api_key()` (lines 16-21) and marks completion with `SETUP_COMPLETE=true` (lines 42-58).
- **Loading**: [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) reads the file via `read_env_file()` (lines 17-45) and merges values into the environment.
- **Precedence**: Groq keys take priority over OpenAI keys when both are present in the configuration file.

## Frequently Asked Questions

### What happens if I include both GROQ_API_KEY and OPENAI_API_KEY in the file?

If both variables are present in `~/.config/watch/.env`, `claude-video` prioritizes the `GROQ_API_KEY` for Whisper transcription. The backend selection logic in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) checks for the Groq key first and only falls back to the OpenAI endpoint if the Groq key is absent.

### Can I manually create the ~/.config/watch/.env file without running the setup script?

Yes, you can manually create the directory and file. However, running [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) is recommended because it validates the directory structure, creates the proper template, and runs `_have_api_key()` to verify your credentials. Manual creation skips the `SETUP_COMPLETE=true` marker (lines 42-58) that the installer writes to confirm successful initialization.

### How do I verify that claude-video recognizes my API key?

Run the setup script with the `--check` flag: `python3 -m skills.watch.scripts.setup --check`. This executes the validation routine in `_have_api_key()` (lines 16-21) and returns exit code 0 if a valid key is detected. You can also check programmatically by importing `get_config()` from [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) and verifying that the configuration loads without errors.

### Where should I obtain the API keys for claude-video?

For the preferred transcription backend, obtain a `GROQ_API_KEY` from [console.groq.com/keys](https://console.groq.com/keys). For the fallback option, obtain an `OPENAI_API_KEY` from [platform.openai.com/api-keys](https://platform.openai.com/api-keys). Insert either key into `~/.config/watch/.env` following the `KEY=VALUE` format.