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

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 and 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 delegates argument parsing to utility functions that detect this flag early in the execution flow.

Early Flag Detection in book_to_skill/utils.py

According to the source code in 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 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:

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:

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: The thin CLI wrapper that imports book_to_skill.cli.main and delegates to utility functions for argument handling.
• 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: Implements the full dependency-scanning logic, defining which packages are required for each document format and generating installation hints.
• docs/install.md and 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 via early detection in 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. 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 (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.

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 that lists required Python modules and system executables.

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