CLI Arguments for the `scripts/extract.py` Script in book-to-skill: Complete Reference

The scripts/extract.py entry-point supports --mode for extraction strategy selection, --install-missing for dependency handling, --check for environment validation, and positional file path arguments, with all parsing logic implemented in book_to_skill/utils.py.

The virgiliojr94/book-to-skill repository provides a command-line tool for extracting text and technical content from PDF and ebook documents. While scripts/extract.py serves as the executable launcher, the actual CLI argument parsing and validation reside in the core book_to_skill package, specifically within the utils.py module.

Where CLI Arguments Are Defined

Although scripts/extract.py acts as the wrapper—inserting the project root into sys.path and delegating to book_to_skill.cli.main—the argument parsing logic lives in book_to_skill/utils.py. The parse_arguments function (lines 82-106) manually walks through sys.argv to extract configuration options, while the main function (lines 73-84) orchestrates execution and handles special flags like --help and --check.

Complete List of Supported CLI Arguments

The script accepts both optional flags and positional arguments for input specification.

Extraction Mode Selection (--mode)

The --mode flag controls which extraction engine processes the documents:

• technical — Uses the layout-aware Docling extractor for PDF documents
• text — Default mode; uses plain-text tools like pdftotext, pypdf, or pdfminer

If an unsupported mode is supplied, the parser falls back to "text" (lines 112-114 in book_to_skill/utils.py).

Dependency Installation Control (--install-missing / --no-install-missing)

These flags govern automatic installation of missing third-party tools:

• --install-missing — Accepts ask (prompt user), yes (install silently), or no (error if missing). Can also be used without a value.
• --no-install-missing — Explicitly disables automatic installation of missing dependencies.

The raw flag values are later normalized by normalize_install_mode in book_to_skill/dependencies.py to determine concrete behavior.

Environment Validation (--check)

The --check flag triggers a dependency check via run_dependency_check and exits immediately, reporting which extractors are installed and available.

Help Display (-h, --help)

Displays the usage banner defined in print_usage (lines 59-66 of book_to_skill/utils.py) and exits without processing files.

Positional Arguments

One or more file paths, directories, or glob patterns pointing to documents to process. These are collected as the input list after all flag parsing completes.

Usage Examples

Technical Extraction with Prompted Installation

book-to-skill /path/to/book.pdf --mode technical --install-missing ask

Uses the Docling extractor for PDFs and prompts the user to install any missing tools.

Batch Processing with Disabled Auto-Install

book-to-skill ~/books/*.epub --no-install-missing

Processes all EPUB files under ~/books; errors out if required dependencies (e.g., ebooklib) are missing.

Checking Installed Extractors

book-to-skill --check

Exits with a status code indicating whether all optional extractors are available.

Internal Argument Processing Flow

The CLI handling follows a specific sequence within book_to_skill/utils.py:

1. Initial Inspection — The main function checks for --help or -h and prints the usage string from print_usage.
2. Dependency Check — If --check is present, main calls run_dependency_check from book_to_skill/dependencies.py and exits.
3. Parsing — parse_arguments iterates through argv, extracting --mode and install-related flags, collecting remaining strings as input paths.
4. Validation — Unsupported modes fall back to "text" (lines 112-114).
5. Normalization — The normalize_install_mode helper converts raw install flags into concrete behavior (ask, yes, no).

Any unrecognized flags trigger a warning and are ignored by the parser.

Summary

• scripts/extract.py serves as a thin wrapper that delegates to book_to_skill.cli.main, with actual parsing in book_to_skill/utils.py
• Supported flags include --mode, --install-missing, --no-install-missing, --check, and --help
• Positional arguments specify file paths, directories, or glob patterns for document discovery
• The parse_arguments function manually processes sys.argv at lines 82-106 to extract configuration
• Dependency installation behavior is normalized through book_to_skill/dependencies.py

Frequently Asked Questions

What does the --mode flag do in scripts/extract.py?

The --mode flag selects the extraction strategy. Set it to technical to use the layout-aware Docling extractor for PDF documents, or use text (the default) for plain-text extraction tools like pdftotext or pdfminer according to the book_to_skill source code.

How does --install-missing handle dependencies?

The --install-missing flag controls whether missing third-party tools are installed automatically. It accepts ask (prompt user), yes (install silently), or no (error if missing). Alternatively, use --no-install-missing to explicitly disable this behavior, as implemented in the normalize_install_mode helper.

Why does scripts/extract.py not contain the argument parsing logic?

The scripts/extract.py file serves purely as an entry-point wrapper that ensures the project root is in sys.path before importing and calling book_to_skill.cli.main. All argument parsing, validation, and execution logic resides in book_to_skill/utils.py to maintain separation between the executable script and core library code.

How can I verify that all required extractors are installed?

Run the script with the --check flag. This executes run_dependency_check from book_to_skill/dependencies.py, reports which extractors are available, and exits with a status code indicating the environment's readiness for document processing.

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