# How book-to-skill Parses Command-Line Arguments for Extraction

> Discover how book-to-skill parses command-line arguments using argparse for efficient extraction of data. Learn about its options for logging, output, and input.

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

---

**book-to-skill parses command-line arguments through the `_parse_args()` helper in [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py), which configures an `argparse.ArgumentParser` instance to handle verbose logging, JSON output, file destinations, configuration files, and input sources before routing to format-specific parsers.**

The virgiliojr94/book-to-skill repository implements a deterministic extraction pipeline for converting various document formats into structured text. Understanding how it parses command-line arguments for extraction requires examining the interface between the CLI entry point and the parser autodetection system.

## The Argument Parser Architecture

In [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py), the private function `_parse_args()` (lines 14-44) encapsulates all command-line interface logic. This function instantiates an `argparse.ArgumentParser` with the prog name `"extract"` and a description for extracting structured text from documents. It accepts an optional `argv` parameter of type `list[str] | None`, enabling both programmatic invocation and direct CLI usage.

The parser configuration follows a standard `argparse` pattern, defining boolean flags, path arguments, and positional inputs that control the extraction behavior.

## Supported Command-Line Arguments

The extraction script recognizes six distinct argument categories defined in the `_parse_args()` implementation:

**Version Flag (`-V`, `--version`)**  
Displays the current package version using the `__version__` import from `book_to_skill` and immediately exits.

**Verbose Logging (`-v`, `--verbose`)**  
Enables DEBUG-level logging when present, defaulting to INFO level otherwise.

**JSON Output Format (`-j`, `--json`)**  
Emits one JSON line per extracted entry instead of raw text strings.

**Output Destination (`-o`, `--output`)**  
Accepts a `Path` type argument specifying a file to receive output. When omitted, results print to STDOUT.

**Configuration File (`-c`, `--config`)**  
Loads an optional JSON configuration file passed to the underlying parser as a dictionary.

**Source Document (`src`)**  
A positional argument defaulting to `"-"` (STDIN). Accepts file paths or the hyphen character to read from standard input.

## From Arguments to Execution

The `main()` function (line 46) consumes the `argparse.Namespace` returned by `_parse_args()` to orchestrate the extraction pipeline:

1. **Logging Configuration**: Sets `logging.DEBUG` if `args.verbose` is true, otherwise `logging.INFO`.
2. **Config Loading**: Opens and parses the JSON file specified by `args.config` if provided.
3. **Stream Selection**: Opens `args.src` in binary read mode unless the value is `"-"`, in which case it uses `sys.stdin.buffer`.
4. **Parser Selection**: Calls `autodetect.select_parser(args.src)` to determine the appropriate parser based on file extension.

## Parser Autodetection Integration

The `src` argument directly drives parser selection through [`book_to_skill/parsers/autodetect.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/autodetect.py). The `select_parser()` function (lines 14-33) normalizes the file extension to lowercase and maps it to specific parser modules:

- `.txt` or empty extension → `text` parser
- `.rtf` → `rtf` parser  
- `.pdf` → `pdf` parser
- `.html`, `.htm` → `html` parser
- `.epub` → `epub` parser
- `.docx` → `docx` parser
- `.cbz`, `.cbr` → `calibre` parser
- Unknown extensions fall back to the generic `text` parser

This mapping occurs before extraction begins, ensuring the correct parser class handles the input stream.

## Practical Usage Examples

Extract text from a PDF with default settings:

```bash
python scripts/extract.py book.pdf

```

Enable verbose debugging and output structured JSON to a file:

```bash
python scripts/extract.py -v -j -o skills.json manual.pdf

```

Process an EPUB using a custom configuration file:

```bash
python scripts/extract.py -c parser_config.json ebook.epub

```

Read from STDIN and output plain text:

```bash
cat document.txt | python scripts/extract.py -v -

```

## Summary

- **Entry Point**: [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) contains the CLI logic in `_parse_args()` and `main()`.
- **Argument Parsing**: Uses Python's `argparse` module to define flags for version, verbosity, JSON output, output files, and configuration.
- **Input Handling**: The `src` positional argument accepts file paths or `"-"` for STDIN, defaulting to standard input.
- **Parser Routing**: File extensions determine parser selection via [`book_to_skill/parsers/autodetect.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/autodetect.py), with a fallback to the text parser.
- **Output Flexibility**: Supports both STDOUT and file-based output, with optional JSON serialization per extracted entry.

## Frequently Asked Questions

### What command-line arguments does book-to-skill extract accept?

The `extract` command accepts `-V/--version` for version info, `-v/--verbose` for debug logging, `-j/--json` for JSON line output, `-o/--output` for file destinations, `-c/--config` for JSON configuration files, and the positional `src` argument for input sources.

### How does book-to-skill determine which parser to use?

After parsing arguments, `main()` calls `autodetect.select_parser()` in [`book_to_skill/parsers/autodetect.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/autodetect.py), which inspects the file extension of the `src` argument (case-insensitive) and returns the corresponding parser module. Unknown extensions default to the generic text parser.

### Can book-to-skill read input from STDIN instead of a file?

Yes, the `src` argument defaults to `"-"`, which instructs the script to read from `sys.stdin.buffer`. You can explicitly specify the hyphen or simply pipe content into the command without providing a file path.

### How do I enable detailed debugging output during extraction?

Pass the `-v` or `--verbose` flag when invoking the script. This sets the logging level to `DEBUG` in `main()`, causing thelogger to emit detailed information about config loading, parser selection, and extraction progress.