# How to Process Specific Page Ranges from PDF Documents Using Chandra's CLI

> Easily process specific page ranges from PDFs using Chandra's CLI. Learn how the --page-range flag handles expressions like 1-5,7,9-12 for selective OCR processing.

- Repository: [Datalab/chandra](https://github.com/datalab-to/chandra)
- Tags: how-to-guide
- Published: 2026-03-27

---

**Chandra's CLI provides a `--page-range` flag that parses expressions like `"1-5,7,9-12"` to selectively render only specified pages during OCR processing.**

The `datalab-to/chandra` repository offers a command-line interface for converting PDF documents to structured markdown and HTML. When working with large documents, you can process specific page ranges from PDF documents using Chandra's CLI to target only the content you need, significantly reducing compute time and resource consumption.

## Using the `--page-range` CLI Option

The `--page-range` argument is defined in **[`chandra/scripts/cli.py`](https://github.com/datalab-to/chandra/blob/main/chandra/scripts/cli.py)** at lines 33‑38 as a string option that accepts comma-separated values and hyphenated intervals. This allows you to specify exact pages or ranges using intuitive syntax such as `"1-3"` for pages 1 through 3, or `"2,5,7-9"` for specific non-contiguous selections.

When you invoke the CLI, the flag value is captured and placed into a configuration dictionary. At line 236, this configuration is forwarded to the `load_file` function, which initiates the document processing pipeline with your specified constraints.

## How Page Range Parsing Works Internally

### From CLI Argument to Config

Inside **[`chandra/input.py`](https://github.com/datalab-to/chandra/blob/main/chandra/input.py)**, the `load_file` function extracts the `page_range` value from the config object and passes it to `parse_range_str` at lines 66‑70. This function handles the transformation of the human-readable string into machine-processable data.

### Parsing the Range String

The `parse_range_str` function (lines 53‑62 in **[`chandra/input.py`](https://github.com/datalab-to/chandra/blob/main/chandra/input.py)**) implements the core parsing logic:

- Splits the input string on commas to separate individual entries
- Expands hyphenated intervals (e.g., `"7-9"` becomes 7, 8, 9)
- Deduplicates and sorts the resulting integers
- Returns a Python list of page numbers

This produces a clean list of integers representing the 1-based page numbers as typed by the user.

### Zero-Based Index Mapping

During PDF rendering, **[`chandra/input.py`](https://github.com/datalab-to/chandra/blob/main/chandra/input.py)**'s `load_pdf_images` function iterates over the document pages (line 37). It applies the filter at line 38 using the check `if not page_range or page in page_range:`, where `page` represents the zero-based index.

Because the parsed list contains 1-based numbers while the PDF iterator uses 0-based indices, specifying `"1"` in your range string targets the first physical page (index 0). This mapping occurs automatically during the comparison operation at lines 37‑40.

## Practical Examples

### Process a Continuous Range

To OCR only the first three pages of a document:

```bash
chandra-cli /path/to/document.pdf /output/dir --page-range "1-3"

```

Chandra renders only pages 1, 2, and 3, converts them to PIL images, and processes them through the inference pipeline.

### Process Non-Contiguous Pages

For selective processing of specific pages:

```bash
chandra-cli /data/reports.pdf /results \
    --page-range "2,5,7-9" \
    --include-images \
    --save-html

```

The parser converts `"2,5,7-9"` into the list `[2, 5, 7, 8, 9]`, which maps to zero-based indices `[1, 4, 6, 7, 8]` for internal retrieval.

### Combine with Batch Processing

Page ranges work seamlessly with batch configuration:

```bash
chandra-cli ./books/large.pdf ./out \
    --page-range "10-20" \
    --batch-size 5 \
    --method vllm \
    --max-output-tokens 8000

```

This processes only pages 10 through 20, splitting them into batches of 5 pages each for the vLLM inference backend.

### Programmatic Usage via Python API

You can invoke the CLI functionality directly from Python:

```python
from chandra.scripts.cli import main
from pathlib import Path

main(
    input_path=Path("myfile.pdf"),
    output_path=Path("out"),
    method="vllm",
    page_range="3,6-8",
    max_output_tokens=None,
    max_workers=None,
    max_retries=None,
    include_images=True,
    include_headers_footers=False,
    save_html=True,
    batch_size=2,
    paginate_output=False,
)

```

## Summary

- The **`--page-range`** flag in [`chandra/scripts/cli.py`](https://github.com/datalab-to/chandra/blob/main/chandra/scripts/cli.py) accepts strings like `"1-5,7,9-12"` to limit processing scope.
- **`parse_range_str`** in [`chandra/input.py`](https://github.com/datalab-to/chandra/blob/main/chandra/input.py) handles comma-separated lists and hyphenated ranges, returning sorted unique integers at lines 53‑62.
- **`load_pdf_images`** applies zero-based index filtering at lines 37‑40, mapping your 1-based input to the correct PDF pages.
- This functionality integrates with batch processing parameters and works in both CLI and programmatic contexts.

## Frequently Asked Questions

### What syntax does the `--page-range` option support?

The option accepts comma-separated page numbers and hyphenated intervals. Valid examples include `"1-3"` for pages 1 through 3, `"5,10,15"` for specific pages, and `"1-5,7,9-12"` for mixed ranges. According to the [`chandra/input.py`](https://github.com/datalab-to/chandra/blob/main/chandra/input.py) source code, the parser automatically deduplicates and sorts the results.

### Does Chandra use 0-based or 1-based page indexing?

You specify pages using 1-based indexing (where page 1 is the first page), but internally [`chandra/input.py`](https://github.com/datalab-to/chandra/blob/main/chandra/input.py) uses 0-based indices. When `load_pdf_images` checks `if page in page_range` at line 38, it matches your input of `"1"` against index 0, `"2"` against index 1, and so forth.

### Where is the page filtering logic implemented?

The filtering occurs in **[`chandra/input.py`](https://github.com/datalab-to/chandra/blob/main/chandra/input.py)**. The `parse_range_str` function (lines 53‑62) parses the string into a list, and `load_pdf_images` (lines 37‑40) applies this list to select which pages to render as PIL images during the loading phase.

### Can I use page ranges with batch processing?

Yes. The `--page-range` parameter operates independently of `--batch-size` and other processing flags. Chandra first determines which pages to include based on your range, then groups those selected pages into batches according to your batch size configuration.