# How to Use pdf-inspector CLI Tools: Complete Installation and Usage Guide

> Install pdf-inspector CLI tools and master pdf2md for PDF-to-Markdown conversion and detect-pdf for PDF classification. Get the complete installation and usage guide.

- Repository: [Firecrawl/pdf-inspector](https://github.com/firecrawl/pdf-inspector)
- Tags: how-to-guide
- Published: 2026-08-31

---

**Install the pdf-inspector CLI tools with `cargo install pdf-inspector` to get the `pdf2md` and `detect-pdf` binaries for PDF-to-Markdown conversion and PDF classification.**

The **pdf-inspector** project from Firecrawl provides fast, Rust-based command-line utilities for PDF processing. This guide covers installation via Cargo, configuration, and practical usage of both CLI tools with concrete examples from the source code.

## Installation via Cargo

The **pdf-inspector** crate is distributed through [crates.io](https://crates.io/crates/pdf-inspector) and compiles two binary targets during installation.

Run the following command to install:

```bash
cargo install pdf-inspector

```

This command:

- Downloads the latest release from crates.io
- Compiles the Rust source code, including the binary implementations in [`src/bin/pdf2md.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs) and [`src/bin/detect_pdf.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/detect_pdf.rs)
- Places both `pdf2md` and `detect-pdf` executables in `~/.cargo/bin/`

### Verify Your PATH Configuration

Ensure Cargo's binary directory is in your shell PATH. Most Cargo installations automatically configure this, but you can verify with:

```bash
echo $PATH | grep cargo

```

If missing, add this line to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):

```bash
export PATH="$HOME/.cargo/bin:$PATH"

```

### Confirm Installation

Test that both tools are accessible:

```bash
pdf2md --help
detect-pdf --help

```

These commands display available options and confirm proper installation, as documented in the repository README under the "CLI" section【file:/cache/repos/github.com/firecrawl/pdf-inspector/main/README.md:28-34】.

## Using pdf2md for PDF-to-Markdown Extraction

The **`pdf2md`** binary extracts text content from PDF files and outputs clean Markdown. The implementation resides in [`src/bin/pdf2md.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs), which parses CLI arguments and executes the extraction pipeline.

### Basic PDF to Markdown Conversion

Convert a single PDF file:

```bash
pdf2md document.pdf

```

This outputs Markdown directly to stdout.

### JSON Output for Programmatic Use

For integration with other tools, use the `--json` flag:

```bash
pdf2md document.pdf --json

```

The JSON format structures the extraction results for parsing by downstream applications.

## Using detect-pdf for PDF Classification

The **`detect-pdf`** binary classifies PDFs by type—distinguishing text-based PDFs from scanned documents. The logic is implemented in [`src/bin/detect_pdf.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/detect_pdf.rs).

### Basic PDF Classification

Classify a PDF file:

```bash
detect-pdf document.pdf

```

### JSON Classification Output

Get structured classification results:

```bash
detect-pdf document.pdf --json

```

This is useful for batch processing pipelines where you need to route different PDF types through appropriate handlers.

## Complete CLI Usage Examples

Here are common workflows combining both tools:

```bash

# Install the CLI tools

cargo install pdf-inspector

# Convert a PDF to Markdown

pdf2md document.pdf

# Get JSON-structured output (useful for piping)

pdf2md document.pdf --json

# Classify a PDF (text-based, scanned, etc.)

detect-pdf document.pdf

# Classification with JSON output

detect-pdf document.pdf --json

```

## Key Source Files and Architecture

Understanding the source structure helps with advanced usage and debugging:

| File | Purpose |
|------|---------|
| [`src/bin/pdf2md.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs) | CLI argument parsing and execution for the `pdf2md` binary |
| [`src/bin/detect_pdf.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/detect_pdf.rs) | Fast PDF classification routine for the `detect-pdf` binary |
| [`Cargo.toml`](https://github.com/firecrawl/pdf-inspector/blob/main/Cargo.toml) | Crate manifest declaring both binary targets and dependencies |
| [`README.md`](https://github.com/firecrawl/pdf-inspector/blob/main/README.md) | Quick-start documentation with installation and usage instructions |

The [`Cargo.toml`](https://github.com/firecrawl/pdf-inspector/blob/main/Cargo.toml) file defines both binaries explicitly, allowing Cargo to build and install them as separate command-line tools.

## Summary

- **Install** pdf-inspector CLI tools with `cargo install pdf-inspector`
- **`pdf2md`** converts PDFs to Markdown with optional JSON output via `--json`
- **`detect-pdf`** classifies PDF types with structured output support
- Both binaries compile from Rust source in `src/bin/` and install to `~/.cargo/bin/`
- Ensure your PATH includes Cargo's binary directory for system-wide access

## Frequently Asked Questions

### What are the system requirements for pdf-inspector?

You need **Rust and Cargo** installed on your system. The compilation process builds native binaries optimized for your platform. No additional runtime dependencies are required since the Rust binaries are self-contained.

### How do I update pdf-inspector to the latest version?

Run `cargo install pdf-inspector --force` to reinstall and overwrite existing binaries with the latest release from crates.io. Cargo automatically fetches the newest version and recompiles both `pdf2md` and `detect-pdf`.

### Can I use pdf-inspector without installing it globally?

Yes. Clone the repository and run `cargo run --bin pdf2md -- <arguments>` or `cargo run --bin detect-pdf -- <arguments>` from the project directory. This builds and executes the tools without installing to `~/.cargo/bin/`.

### What PDF types does detect-pdf recognize?

The `detect-pdf` tool distinguishes between text-based PDFs (with extractable text layers) and scanned/image-based PDFs that require OCR. The classification helps determine whether direct text extraction will succeed or if alternative processing is needed.