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

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 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 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 recognizes two supported keys:

• GROQ_API_KEY: Preferred Whisper-large-v3 key (cheaper and faster). Obtain from console.groq.com/keys.
• OPENAI_API_KEY: Fallback Whisper key from 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 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 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 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 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:

python3 -m skills.watch.scripts.setup

On first run, the output confirms creation:

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

This invokes the file creation logic in 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:

nano ~/.config/watch/.env

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

# ~/.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:

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:

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 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 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 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 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 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. For the fallback option, obtain an OPENAI_API_KEY from platform.openai.com/api-keys. Insert either key into ~/.config/watch/.env following the KEY=VALUE format.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}