# How the Claude Video `setup.py` Preflight Check Validates Your Environment

> Discover how the Claude Video setup.py preflight check validates your environment, ensuring essential binaries and API keys are ready for the /watch skill. Learn about its exit code signals for readiness and deficiencies.

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

---

**The `cmd_check` function in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) validates that required binaries (`ffmpeg`, `ffprobe`, `yt-dlp`) and Whisper API keys are present before the `/watch` skill executes, returning specific exit codes (0, 2, 3, or 4) to signal readiness or specific deficiencies.**

Before the Claude Video `/watch` skill processes any video, it runs a preflight check to ensure the environment is properly configured. The [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) preflight check function in Claude Video performs this validation by examining system dependencies and credentials without modifying any files. This check lives in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) and is designed to be idempotent, allowing it to run silently on every invocation while only alerting users when action is required.

## The Core Logic: `cmd_check` and `_status()`

The heart of the preflight validation resides in the **`cmd_check`** function, which delegates state gathering to the internal **`_status()`** helper. Together, these functions determine whether the environment is ready for video processing according to the `bradautomates/claude-video` source code.

### Collecting the Status Snapshot

The `_status()` function aggregates four critical data points by calling specialized helpers:

- **Binary verification**: `_check_binaries()` scans the system for `ffmpeg`, `ffprobe`, and `yt-dlp` executables.
- **API key presence**: `_have_api_key()` checks for `GROQ_API_KEY` or `OPENAI_API_KEY` environment variables required for Whisper transcription.
- **Installation history**: `is_first_run()` verifies whether `SETUP_COMPLETE=true` exists in the configuration.
- **User configuration**: `get_config()` from [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) retrieves platform details and the user-defined watch detail level (`cfg["detail"]`).

### Determining Environment State

Based on the snapshot, `_status()` derives one of four high-level states:

- **`ready`**: All binaries present **and** a Whisper API key is configured.
- **`needs_key`**: Binaries exist but no API key is set (indicates a first run).
- **`needs_install`**: Binaries are missing but a key is present (indicates a failed or incomplete installation).
- **`needs_install_and_key`**: Both binaries and API keys are absent.

The function also computes **`can_proceed`**, which evaluates to true only when binaries exist **and** either a valid API key is present **or** the installer has previously completed (`SETUP_COMPLETE=true`).

### Exit Code Strategy

The `cmd_check` function translates the status snapshot into actionable exit codes:

- **Exit 0**: `can_proceed` is true. The environment is ready and `/watch` can execute silently.
- **Exit 2**: Binaries are missing but an API key exists (or a previous installation failed).
- **Exit 3**: Binaries are present but no API key is configured, and the installer has never completed (genuine first-run scenario).
- **Exit 4**: Both binaries **and** an API key are missing.

When returning a non-zero code, `cmd_check` prints a concise, actionable message to **stderr** (e.g., "missing binaries: ffmpeg, yt-dlp; no Whisper API key").

## Idempotent Safety Design

Because **`cmd_check`** only inspects state and never writes configuration files or modifies the environment, it remains completely **idempotent**. This design allows the watch skill to invoke the preflight check on every turn without generating repetitive "setup complete" messages. The function acts as a read-only gatekeeper, ensuring users only receive warnings when dependencies are genuinely missing.

## Running the Preflight Check

You can execute the preflight check directly from the command line or integrate it into Python scripts.

To verify your environment from the terminal:

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

# Exit 0 indicates success; exits 2-4 trigger stderr warnings with specific deficiency details

```

To invoke the check programmatically from another Python script:

```python
import subprocess
import sys

result = subprocess.run(
    [sys.executable, "-m", "skills.watch.scripts.setup", "--check"],
    capture_output=True,
    text=True,
)

if result.returncode == 0:
    print("✅ Environment ready for Claude Video processing")
else:
    print(f"⚠️ Setup needed: {result.stderr.strip()}")
    sys.exit(result.returncode)

```

## Integration with the Watch Skill

The preflight check integrates directly with the video processing pipeline. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the entry point for the `/watch` skill invokes `setup.cmd_check()` before processing any video URL. This ensures that Claude Video only attempts transcription when all required binaries are available and a Whisper backend is properly configured, preventing mid-process failures due to missing dependencies.

## Summary

- The **`cmd_check`** function in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) serves as the gatekeeper for the Claude Video `/watch` skill.
- It validates presence of `ffmpeg`, `ffprobe`, `yt-dlp`, and Whisper API keys (`GROQ_API_KEY` or `OPENAI_API_KEY`).
- Returns **exit codes 0, 2, 3, or 4** to indicate specific readiness states or deficiencies.
- Uses **`can_proceed`** logic to distinguish between ready environments and those requiring setup.
- Designed to be **idempotent** and safe for repeated execution without side effects.

## Frequently Asked Questions

### What exit codes does the Claude Video setup.py preflight check return?

The preflight check returns four specific exit codes. Exit 0 indicates the environment is ready. Exit 2 signals missing binaries (ffmpeg, ffprobe, or yt-dlp). Exit 3 indicates binaries are present but no Whisper API key is configured. Exit 4 means both binaries and API keys are missing.

### Which binaries does the preflight check verify?

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 `_check_binaries()` function verifies the presence of three required executables: **`ffmpeg`**, **`ffprobe`**, and **`yt-dlp`**. These tools handle video download, processing, and metadata extraction for the Claude Video workflow.

### How does the preflight check determine if it's a first run?

The check uses the `is_first_run()` helper to look for `SETUP_COMPLETE=true` in the configuration. If this flag is absent and no API key is present, the `_status()` function classifies the state as `needs_key` or `needs_install_and_key`, triggering exit code 3 or 4 respectively.

### Can I run the setup.py preflight check multiple times safely?

Yes. The `cmd_check` function is read-only and never modifies files or environment variables. This idempotent design allows it to run repeatedly without side effects, making it safe to invoke before every video processing operation in the Claude Video workflow.