# Setup Preflight Process and First-Run Detection in Claude-Video > Learn how Claude-Video's setup preflight process and first-run detection ensure successful installation. The script checks binaries and API keys, guiding users through setup when needed. - Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) - Tags: how-to-guide - Published: 2026-07-10 --- **Claude-Video's watch skill uses a Python pre-flight script ([`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py)) that checks for required binaries and API keys, exits silently on success, and guides users through first-run installation when the `SETUP_COMPLETE` flag is missing from `~/.config/watch/.env`.** The bradautomates/claude-video repository ships a dedicated watch skill that requires specific external dependencies and API credentials before it can process video content. Understanding the setup preflight process ensures you can diagnose configuration issues quickly and confirm that your environment is ready for the `/watch` command. ## How First-Run Detection Works The `is_first_run()` function in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) determines whether the setup wizard needs to execute by checking the user configuration file at `~/.config/watch/.env`. Specifically, the function inspects the `SETUP_COMPLETE` environment variable (lines 124-127). If this variable is unset or not equal to `"true"`, the function returns `True`, signaling that the user has not yet completed the initial installation workflow. This flag serves as a persistent marker across sessions. Once the installation flow successfully detects a valid Whisper API key and writes `SETUP_COMPLETE=true` to the `.env` file, subsequent runs skip the interactive setup prompts. ## Pre-flight Verification Logic Before the `/watch` command can execute, the `cmd_check()` function (invoked with the `--check` flag) performs a comprehensive environment verification via the internal `_status()` helper (lines 59-71). ### Binary Availability Checks The `_check_binaries()` function verifies that `ffmpeg`, `ffprobe`, and `yt-dlp` are present on the system `PATH`. Any missing binaries are recorded in the status dictionary for later reporting. ### API Key Validation The `_have_api_key()` function searches for transcription credentials by first checking environment variables, then falling back to the `.env` file via `_read_env_key()`. Claude-Video supports both **Groq** and **OpenAI** API keys for Whisper transcription services. ### Status State Machine The `_status()` function (lines 17-28) aggregates these checks into a structured dictionary containing four possible states in the `status` field: - `ready` – All dependencies present and API key configured - `needs_install` – Missing required binaries - `needs_key` – First run without API key - `needs_install_and_key` – Both binaries and API key missing ## Installation and Setup Workflow When executed without flags, `cmd_install()` (lines 99-115) enters the default installation mode. This workflow handles platform-specific dependency management and environment scaffolding. On **macOS**, the script attempts to auto-install missing binaries using the appropriate package manager. On **Linux** and **Windows**, it prints platform-specific installation hints rather than attempting automated installation. The function also ensures the configuration directory exists at `~/.config/watch/` and scaffolds a placeholder `.env` file if one does not already exist. This prevents the loss of user-configured settings like `watch_detail` between runs. ### Completing First-Run Setup The installation process marks setup completion only when `_have_api_key()` detects a valid Whisper API key. At that point, the script writes `SETUP_COMPLETE=true` to the `.env` file (lines 34-41), ensuring `is_first_run()` will return `False` on subsequent executions. ## Silent Check Mode and Exit Codes The pre-flight system supports a silent operation mode designed for integration with the main `/watch` entry point. When called with `--check`, the script exits with status `0` and produces no output if the environment is ready (`can_proceed` is `True`). If checks fail, the script prints a single actionable error line to `stderr` and returns a specific exit code: - **Exit code 2** – Required binaries are missing - **Exit code 3** – First run detected without an API key - **Exit code 4** – Both binaries missing and no API key configured This design allows the parent process to distinguish between recoverable configuration errors and runtime failures without parsing verbose log output. ## Running the Setup Script You can invoke the pre-flight checks manually to verify your environment or trigger the installation wizard. Run a silent pre-flight check (used internally by `/watch`): ```bash python3 skills/watch/scripts/setup.py --check ``` Print a machine-readable status snapshot: ```bash python3 skills/watch/scripts/setup.py --json ``` Perform a full installation (first run): ```bash python3 skills/watch/scripts/setup.py ``` The full installation installs missing binaries on macOS, prints hints for other platforms, scaffolds `~/.config/watch/.env`, and writes `SETUP_COMPLETE=true` once a valid API key is detected. ## Summary - The `is_first_run()` function in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) checks the `SETUP_COMPLETE` flag in `~/.config/watch/.env` to determine if initial setup is required. - Pre-flight verification validates the presence of `ffmpeg`, `ffprobe`, and `yt-dlp` binaries plus a Whisper API key (Groq or OpenAI). - The `_status()` function encodes environment readiness into four states: `ready`, `needs_install`, `needs_key`, or `needs_install_and_key`. - Silent mode (`--check`) returns exit code `0` on success, or codes `2`, `3`, or `4` to indicate specific missing dependencies. - The installation workflow is idempotent, preserving existing API keys and only writing the completion flag when credentials are confirmed. ## Frequently Asked Questions ### How does Claude-Video detect if it has been run before? Claude-Video detects first-run status by reading the `SETUP_COMPLETE` environment variable from the `.env` file located at `~/.config/watch/`. If this variable is missing or not set to `"true"`, the `is_first_run()` function returns `True`, triggering the installation wizard. ### What external dependencies are required for the watch skill? The watch skill requires three external binaries: `ffmpeg`, `ffprobe`, and `yt-dlp`. These must be available on the system `PATH` before the `/watch` command can process video content. Additionally, you must configure either a `GROQ_API_KEY` or `OPENAI_API_KEY` for Whisper transcription services. ### Can I run the setup script multiple times safely? Yes, the setup process is idempotent. Re-running [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) will not overwrite existing API keys in your `.env` file, and the script only marks setup as complete when it detects a valid Whisper key. You can safely run the script to verify binary availability or update your configuration. ### What do the different exit codes mean when using --check? Exit code `0` indicates the environment is ready for the `/watch` command. Exit code `2` means required binaries are missing, code `3` indicates a first-run scenario without an API key, and code `4` signals that both binaries and an API key are needed. These codes allow automated tools to handle specific configuration errors programmatically.