# What Is Verified During the Watch Skill Setup Preflight Check?

> Understand the watch skill setup preflight check. Learn what's verified, including binaries, API keys, and the setup completion flag, ensuring a smooth installation.

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

---

**The watch skill setup preflight check verifies three requirements: required binaries (ffmpeg, ffprobe, and yt-dlp), a valid Whisper API key (GROQ_API_KEY or OPENAI_API_KEY), and the SETUP_COMPLETE flag that indicates the installer has run.**

The `bradautomates/claude-video` repository provides a `/watch` skill for video processing that depends on external tools and transcription services. Before the skill executes, it runs a **watch skill setup preflight check** using the `--check` mode in [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) to validate the environment. This verification ensures that all dependencies are present and properly configured, preventing runtime failures during video processing.

## Required External Binaries

The preflight check first verifies that essential media processing tools are installed and accessible in the system PATH. In [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py), the `_check_binaries()` function uses `shutil.which` to scan for three specific executables:

- **ffmpeg**
- **ffprobe** 
- **yt-dlp**

If any binary is missing, the check sets the status to `needs_install` or `needs_install_and_key` (when combined with a missing API key). The function collects all missing binaries into the `missing_binaries` list for targeted troubleshooting.

## Whisper API Credentials

The second verification ensures that a transcription backend is available. The `_have_api_key()` function checks for a valid API key in two locations:

1. **Environment variables**: `GROQ_API_KEY` or `OPENAI_API_KEY`
2. **Configuration file**: `~/.config/watch/.env`

The check searches for either key to determine the `whisper_backend` (Groq or OpenAI) and sets `has_api_key` accordingly. If no key is found and the setup wizard has not completed, the status becomes `needs_key` or `needs_install_and_key`.

## First-Run Completion Status

The final check determines whether the initial setup has been executed. The `is_first_run()` function looks for `SETUP_COMPLETE=true` inside the `.env` configuration file at `~/.config/watch/.env`.

If the flag is absent, the skill treats the session as a first run and may display the setup wizard. Once `SETUP_COMPLETE` is present, the user is considered to have finished the installer, even if no API key was added (allowing for optional transcription workflows).

## Status Aggregation and Exit Codes

The `_status()` helper in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) aggregates these checks into a structured snapshot containing:

- **`status`**: One of `ready`, `needs_install`, `needs_key`, or `needs_install_and_key`
- **`can_proceed`**: `True` only when all binaries are present **and** either an API key exists **or** the setup flag is set
- **`missing_binaries`**: List of any binaries not found in PATH
- **`has_api_key`** and **`whisper_backend`**: Indication of which transcription service is configured
- **`first_run`** and **`setup_complete`**: Boolean flags reflecting the setup state
- **`platform`**: Operating system name for tailored installation hints

When invoked via `cmd_check()`, the preflight exits with specific codes:

- **0**: Everything is ready (silent success)
- **2**: Required binaries are missing
- **3**: First run without an API key (prompts to add a key)
- **4**: Both binaries missing and no API key available

## Running the Preflight Check

You can execute the watch skill setup preflight check using the following commands:

```bash

# Quietly verify that /watch can run (no output on success)

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

# → exits 0 if ready, otherwise prints a helpful error to stderr

```

For debugging or CI pipelines, output the verification results as JSON:

```bash

# Get a machine‑readable JSON status

python3 -m skills.watch.scripts.setup --json

```

Example JSON output:

```json
{
  "status": "needs_key",
  "can_proceed": false,
  "first_run": true,
  "setup_complete": false,
  "missing_binaries": [],
  "whisper_backend": null,
  "has_api_key": false,
  "config_file": "/home/you/.config/watch/.env",
  "watch_detail": "balanced",
  "platform": "Linux"
}

```

To run the full interactive installer that adds missing binaries (on macOS), scaffolds the `.env` file, and sets the completion flag:

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

```

## Summary

- The **watch skill setup preflight check** validates three core requirements: external binaries (`ffmpeg`, `ffprobe`, `yt-dlp`), API credentials (`GROQ_API_KEY` or `OPENAI_API_KEY`), and the `SETUP_COMPLETE` flag in `~/.config/watch/.env`.
- The `_status()` function in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) aggregates verification results into a structured report including `can_proceed`, `missing_binaries`, and `whisper_backend`.
- Exit codes provide actionable feedback: 0 for ready, 2 for missing binaries, 3 for missing API key, and 4 for multiple deficiencies.
- The `--check` mode enables silent verification suitable for scripting, while `--json` provides detailed diagnostics for troubleshooting.

## Frequently Asked Questions

### What happens if the preflight check fails?

If the preflight check detects issues, `cmd_check()` prints a single actionable error message to stderr and exits with a specific code. Exit code 2 indicates missing binaries, code 3 indicates a missing API key on first run, and code 4 indicates both binaries and keys are absent. These specific codes allow automated scripts to handle different failure modes appropriately.

### Where does the watch skill look for API keys?

The skill searches for `GROQ_API_KEY` or `OPENAI_API_KEY` in environment variables first, then falls back to the `~/.config/watch/.env` file. According to the source code in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py), the `_have_api_key()` function checks both locations to determine which Whisper backend (Groq or OpenAI) will be used for transcription.

### Can I run the skill without an API key?

Yes, you can proceed without an API key if you have completed the initial setup. The `can_proceed` logic in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) returns `True` when either an API key exists **or** the `SETUP_COMPLETE` flag is set to true. This allows users to opt out of transcription features while still using other video processing capabilities.

### What files are involved in the preflight verification?

The primary implementation resides in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py), which contains the `_check_binaries()`, `_have_api_key()`, `is_first_run()`, and `_status()` functions. Configuration reading is handled by [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), and the verification logic is validated by unit tests in [`tests/test_setup.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_setup.py).