# What Does the `--check` Flag Do in the book-to-skill Extractor Script?

> Learn what the --check flag does in the book-to-skill extractor script. It scans your environment for optional dependencies, reports availability, and exits without processing files.

- Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill)
- Tags: how-to-guide
- Published: 2026-08-30

---

**The `--check` flag is a pre-flight diagnostic that scans your environment for optional dependencies required by the virgiliojr94/book-to-skill extractor, prints a human-readable availability report, and exits without processing any input documents.**

The `book-to-skill` extractor script supports multiple document formats—including PDF, EPUB, HTML, DOCX, and RTF—each requiring specific Python packages and system tools for optimal extraction. The `--check` flag provides a quick way to verify that your environment is properly configured before attempting actual document processing. This diagnostic tool is implemented across several modules, specifically within [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) and [`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py).

## How the `--check` Flag Works

When you append `--check` to the CLI command, the entry point in [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) delegates argument parsing to utility functions that detect this flag early in the execution flow.

### Early Flag Detection in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py)

According to the source code in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) (lines 60-62), the system inspects `sys.argv` for the presence of `--check`. If detected, the script immediately invokes `run_dependency_check()` and terminates without loading any document processing logic.

### Dependency Scanning Implementation

The `run_dependency_check()` function is defined in **[`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py)** and performs a comprehensive scan of optional dependencies grouped by document format. The function examines Python modules and system executables specified at the top of the file (around line 13) to determine which extractors are available.

## What the Dependency Check Reports

The diagnostic output from `--check` provides four key pieces of information to help you troubleshoot your environment setup:

1. **Format-by-format dependency scanning.** The function iterates through every supported format (PDF, EPUB, HTML, DOCX, RTF, etc.) and checks for the presence of required Python packages like `pypdf`, `ebooklib`, and `beautifulsoup4`, as well as system binaries such as `pdftotext` from poppler-utils.

2. **Visual status indicators.** For each dependency, the report prints a checkmark (`✓`) for present items or a cross (`✗`) for missing ones, followed by specific installation commands (e.g., `pip install pypdf` or `sudo apt-get install poppler-utils`).

3. **Consolidated installation commands.** If any dependencies are missing, the script generates a consolidated pip install command and system package manager instructions to enable the "best extractor" for every supported format.

4. **Non-fatal exit behavior.** As documented in the docstring (lines 48-50), the function returns exit code `0` regardless of missing optional dependencies because the extractor can fall back to built-in parsers, ensuring CI/CD pipelines don't break due to missing enhancements.

## Practical Examples for Running the Check

### Command Line Usage

To verify your environment from the terminal, execute the following command from the repository root:

```bash
python3 scripts/extract.py --check

```

Sample output shows the status of each extractor group:

```

book-to-skill — dependency check

  PDF extraction
      ✗ python: pypdf
        ↳ pip install pypdf
      ✓ system: pdftotext (poppler-utils)

  EPUB extraction
      ✗ python: ebooklib
        ↳ pip install ebooklib
      ✗ python: bs4
        ↳ pip install beautifulsoup4

...
To enable the best extractor for every format, install the missing pieces:

  /usr/bin/python3 -m pip install pypdf ebooklib beautifulsoup4
  # poppler-utils: sudo apt-get install poppler-utils

```

### Programmatic Integration

You can also invoke the dependency check directly from Python code without using the CLI wrapper:

```python
from book_to_skill.dependencies import run_dependency_check

# Execute the check and capture the exit code (always 0)

exit_code = run_dependency_check()
print(f"Dependency check completed with exit code {exit_code}")

```

## Key Files Implementing the `--check` Functionality

Understanding the codebase structure helps when customizing or debugging the dependency verification system:

- **[`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py)**: The thin CLI wrapper that imports `book_to_skill.cli.main` and delegates to utility functions for argument handling.
- **[`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py)**: Contains the logic that parses CLI arguments and detects the `--check` flag before invoking the diagnostic routine.
- **[`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py)**: Implements the full dependency-scanning logic, defining which packages are required for each document format and generating installation hints.
- **[`docs/install.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/install.md)** and **[`README.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/README.md)**: Provide user-facing documentation explaining how to use `--check` for environment validation.

## Summary

- The `--check` flag triggers `run_dependency_check()` in [`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py) via early detection in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) (lines 60-62).
- It scans for optional Python packages and system binaries required for PDF, EPUB, HTML, DOCX, and RTF extraction.
- The output displays visual indicators (`✓`/`✗`) for each dependency and provides exact installation commands.
- The script always exits with code `0`, allowing the extractor to fall back to built-in parsers if optional dependencies are missing.
- It performs a dry run that processes no input documents, making it safe for CI/CD pre-checks and environment validation.

## Frequently Asked Questions

### Does the `--check` flag modify my system or install packages automatically?

No. The `--check` flag is strictly diagnostic according to the implementation in [`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py). It only reports which dependencies are present or absent and suggests installation commands. It does not execute `pip install` or system package manager commands automatically.

### What exit code does the `--check` flag return if dependencies are missing?

The function returns **exit code `0`** regardless of missing optional dependencies, as implemented in [`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py) (lines 44-53 and 64-85). This non-fatal behavior ensures the extractor can still run using fallback built-in parsers rather than failing the check.

### Can I run the dependency check without using the CLI?

Yes. Import `run_dependency_check` directly from `book_to_skill.dependencies` and call it programmatically. This allows integration into setup scripts, test suites, or custom workflows without invoking [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py).

### Which file formats does the dependency scan cover?

The scan covers all supported document formats including PDF, EPUB, HTML, DOCX, and RTF. Each format has a specific dependency group defined in [`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py) that lists required Python modules and system executables.