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

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 and compiles two binary targets during installation.

Run the following command to install:

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 and 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:

echo $PATH | grep cargo

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

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

Confirm Installation

Test that both tools are accessible:

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, which parses CLI arguments and executes the extraction pipeline.

Basic PDF to Markdown Conversion

Convert a single PDF file:

pdf2md document.pdf

This outputs Markdown directly to stdout.

JSON Output for Programmatic Use

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

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.

Basic PDF Classification

Classify a PDF file:

detect-pdf document.pdf

JSON Classification Output

Get structured classification results:

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:

# 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	CLI argument parsing and execution for the pdf2md binary
src/bin/detect_pdf.rs	Fast PDF classification routine for the detect-pdf binary
Cargo.toml	Crate manifest declaring both binary targets and dependencies
README.md	Quick-start documentation with installation and usage instructions

The 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.

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