### Install pdfvision as a library

Source: https://pdfvision.dev/guide/installation

Install pdfvision as a dependency for your application. Then import the library API to process documents with typed PDF evidence.

```bash
npm install pdfvision
```

--------------------------------

### Verify pdfvision installation

Source: https://pdfvision.dev/guide/installation

Check the installed version and available help options to confirm the installation.

```bash
pdfvision --version
pdfvision --help
```

--------------------------------

### Install pdfvision globally

Source: https://pdfvision.dev/guide/installation

Install pdfvision globally for repeated CLI use. This is the most convenient setup for local agent workflows because every shell can call pdfvision directly.

```bash
npm install -g pdfvision
pdfvision document.pdf
```

--------------------------------

### Install Agent Skills globally via npx

Source: https://pdfvision.dev/guide/agent-skill

Use this command to add the pdfvision skill globally.

```bash
npx skills add yamadashy/pdfvision -g
```

--------------------------------

### Install pdfvision without optional dependencies

Source: https://pdfvision.dev/guide/installation

Install pdfvision without optional dependencies to skip OCR support. Rendering still works because @napi-rs/canvas is a core dependency.

```bash
npm install --omit=optional pdfvision
```

--------------------------------

### Install Agent Skills via npx

Source: https://pdfvision.dev/guide/agent-skill

Use this command to add the pdfvision skill to your project.

```bash
npx skills add yamadashy/pdfvision
```

--------------------------------

### Import and use processDocument

Source: https://pdfvision.dev/guide/installation

Use the library API to process a PDF document. The example extracts pages 1-3 with rendering enabled and logs the total number of pages.

```ts
import { processDocument } from 'pdfvision';

const result = await processDocument('./document.pdf', { pages: '1-3', render: true });
console.log(result.totalPages);
```

--------------------------------

### processFile with format: markdown

Source: https://pdfvision.dev/guide/library-api

Demonstrates how to get the formatted string output from processFile with markdown format and noCache option.

```ts
import { processFile } from 'pdfvision';

const markdown = await processFile('./document.pdf', {
  format: 'markdown',
  pages: '1-2',
  noCache: false,
});
```

--------------------------------

### Run a small extraction with JSON output

Source: https://pdfvision.dev/guide/installation

Run a small extraction on a PDF document and output the result as JSON. This is useful for testing the installation.

```bash
pdfvision document.pdf --json
```

--------------------------------

### processDocument: extract PDF pages with options

Source: https://pdfvision.dev/guide/library-api

Example of using processDocument to extract pages 1-3 with rendering and layout enabled

```ts
import { processDocument } from 'pdfvision';

const result = await processDocument('./document.pdf', {
  pages: '1-3',
  render: true,
  layout: true,
});

console.log(result.totalPages);

for (const page of result.pages) {
  console.log(page.page, page.text);
  if (page.image) console.log(page.image);
}
```

--------------------------------

### Evidence-First Summary Prompt

Source: https://pdfvision.dev/guide/prompt-examples

Use this prompt to generate a summary that treats pdfvision output as evidence, starting from quality fields and warnings, and distinguishing confident text-derived claims from those needing visual verification.

```text
Summarize this PDF using the pdfvision output as evidence.

Rules:
1. Start from overview quality fields and page warnings.
2. Do not summarize pages whose native text is empty, sparse, or glyph-corrupted without saying what evidence is missing.
3. When a conclusion depends on a table, form field, chart, or figure, cite the page and bbox or recommend a crop command.
4. Separate confident text-derived claims from claims that need visual verification.
```

--------------------------------

### Run pdfvision with npx

Source: https://pdfvision.dev/guide/installation

Use this command to run pdfvision without installing it. This is the easiest option for one-off extraction, especially when an agent needs to inspect a PDF once or you want the latest published version without changing a project.

```bash
npx pdfvision document.pdf
```

--------------------------------

### OCR with multiple languages

Source: https://pdfvision.dev/guide/rendering-and-ocr

Uses plus-separated languages for multilingual pages. The example uses English and Japanese.

```bash
pdfvision scan.pdf --ocr --ocr-lang eng+jpn --format json
```

--------------------------------

### Agent integration with conditional rendering

Source: https://pdfvision.dev/guide/library-api

Shows the recommended pattern of first detecting pages needing more detail (e.g., non-'ok' quality or matches) and then rendering those pages individually.

```ts
import { processDocument } from 'pdfvision';

const firstPass = await processDocument('./report.pdf', {
  search: ['revenue', 'operating income'],
  layout: true,
});

const pagesToRender = firstPass.pages.filter((page) => {
  return page.quality.nativeTextStatus !== 'ok' || page.warnings?.length || page.matches?.length;
});

for (const page of pagesToRender) {
  const rendered = await processDocument('./report.pdf', {
    pages: String(page.page),
    render: true,
    layout: true,
  });
  console.log(rendered.pages[0].image);
}
```

--------------------------------

### Run pdfvision with layout reconstruction

Source: https://pdfvision.dev/guide/layout-and-warnings

Use the --layout flag to generate structured output that includes geometry and reading-order information.

```bash
pdfvision document.pdf --layout --format json
```

--------------------------------

### Search PDF with bounding boxes and render crop

Source: https://pdfvision.dev/guide/usage

Search for a term and output JSON with bounding boxes. Pass the matching box to --render-region to create a small crop for visual verification.

```bash
pdfvision report.pdf --search "revenue" --format json
pdfvision report.pdf --pages 3 --render --render-region 120,180,360,140 --render-output ./crops --format json
```

--------------------------------

### Perform regex and case-sensitive searches

Source: https://pdfvision.dev/guide/search-and-region-zoom

Demonstrates advanced search options using regex patterns and case-sensitive matching.

```bash
pdfvision report.pdf --search "Q[1-4] revenue" --search-regex --json
pdfvision report.pdf --search "PDF" --search-case-sensitive --json
```

--------------------------------

### Search-Then-Zoom Evidence Check Prompt

Source: https://pdfvision.dev/guide/prompt-examples

Use this prompt to choose the best evidence location from pages[].matches, reporting page, query, source, matched text, and bbox, and returning exact pdfvision commands with --pages, --render, and --render-region when visual verification is needed.

```text
Use pages[].matches from this pdfvision JSON to choose the best evidence location.

For each relevant match:
1. Report the page, query, source, matched text, and bbox.
2. Decide whether the match needs visual verification.
3. If it does, return the exact pdfvision command with --pages, --render, and --render-region.
4. After the crop is rendered, compare the crop against native text, OCR text, and nearby layout blocks.
```

--------------------------------

### Process a local PDF: pdfvision document.pdf

Source: https://pdfvision.dev/guide/usage

Runs pdfvision on a local PDF file with default settings.

```bash
pdfvision document.pdf
```

--------------------------------

### Reconstruct layout with pdfvision

Source: https://pdfvision.dev/guide

Use layout reconstruction when reading order, columns, tables, forms, or warnings matter. Includes image and vector boxes.

```bash
npx pdfvision document.pdf --layout --image-boxes --vector-boxes --format json
```

--------------------------------

### Region zoom with renderRegion from a bbox

Source: https://pdfvision.dev/guide/library-api

Shows how to use a bbox from a search match to render a zoomed region on one page.

```ts
const [match] = firstPass.pages.flatMap((page) => page.matches ?? []);

if (match?.bbox) {
  const zoom = await processDocument('./report.pdf', {
    pages: String(match.page),
    render: true,
    renderRegion: match.bbox,
    renderScale: 3,
  });

  console.log(zoom.pages[0].image);
}
```

--------------------------------

### Run pdfvision with JSON output using --json alias

Source: https://pdfvision.dev/guide

Runs pdfvision with JSON output using the --json flag, which is an alias for --format json. Recommended for unknown PDFs as a first pass to give the agent a machine-readable overview before deciding on rendering or OCR.

```bash
npx pdfvision document.pdf --json
```

--------------------------------

### Search and crop PDF evidence with pdfvision

Source: https://pdfvision.dev/guide

Search first, then crop only the matching area when exact evidence matters. The second command renders page 3 and crops the specified region.

```bash
npx pdfvision document.pdf --search "revenue" --format json
```

```bash
npx pdfvision document.pdf --pages 3 --render --render-region 120,180,360,140 --render-output ./crops --format json
```

--------------------------------

### Search PDF for evidence

Source: https://pdfvision.dev/guide

Practical default for evidence search.

```bash
npx pdfvision report.pdf --search "term" --json
```

--------------------------------

### Financial Metric Verification Prompt

Source: https://pdfvision.dev/guide/prompt-examples

Use this prompt to verify financial metrics from pdfvision output, finding candidate matches, checking warnings, and returning a --render-region command for ambiguous values.

```text
Use this pdfvision output to verify financial metrics.

For each requested metric:
1. Find candidate matches in pages[].matches or layout table labels.
2. Identify the page, row/column context, and bbox evidence.
3. Check warnings for table flattening, reading-order divergence, dense vectors, or raster-only content.
4. If the value is visually encoded or ambiguous, return a pdfvision --render-region command for the smallest useful crop.
5. Do not invent values from nearby text when row or column alignment is unclear.
```

--------------------------------

### Detect visual structure and regions

Source: https://pdfvision.dev/guide/use-cases

Identify layout, image boxes, vector boxes, and visual regions to prepare for targeted rendering.

```bash
pdfvision report.pdf --layout --image-boxes --vector-boxes --visual-regions --format json
```

--------------------------------

### Crop and render search results

Source: https://pdfvision.dev/guide/use-cases

Use coordinates from search results to render a specific region for auditable evidence.

```bash
pdfvision contract.pdf --pages 9 --render --render-region 96,320,420,96 --render-output ./crops --json
```

--------------------------------

### Render pages for a multimodal model

Source: https://pdfvision.dev/

Renders pages of a PDF to support multimodal model input.

```bash
npx pdfvision document.pdf --render
```

--------------------------------

### Set custom cache directory with PDFVISION_CACHE_DIR

Source: https://pdfvision.dev/guide/usage

Set PDFVISION_CACHE_DIR to a nonblank absolute path for a dedicated cache directory. Relative paths, ~, filesystem roots, home, working directory, and shared temporary roots are refused.

```bash
PDFVISION_CACHE_DIR=/secure/pdfvision-cache pdfvision document.pdf --json
```

--------------------------------

### MCP server configuration for pdfvision

Source: https://pdfvision.dev/guide/mcp-server

JSON configuration for the MCP server, specifying the `pdfvision` server with the command `npx` and arguments `-y pdfvision mcp`. The server is a subcommand of the main binary and takes no arguments, speaking JSON-RPC on stdout.

```json
{
  "mcpServers": {
    "pdfvision": { "command": "npx", "args": ["-y", "pdfvision", "mcp"] }
  }
}
```

--------------------------------

### Render a specific page for inspection

Source: https://pdfvision.dev/guide/layout-and-warnings

Use this command to render page 3 of a document to JSON format, allowing for visual inspection of pages flagged with warnings.

```bash
pdfvision document.pdf -p 3 --render --format json
```

--------------------------------

### Crop PDF region for vision

Source: https://pdfvision.dev/guide

Practical default for a vision crop.

```bash
npx pdfvision report.pdf --pages 2 --render --render-region 120,180,360,140 --render-output ./crops --json
```

--------------------------------

### Render full pages with pdfvision

Source: https://pdfvision.dev/guide/rendering-and-ocr

Renders each selected page to an image and outputs JSON. The image path is returned in pages[].image. Layout boxes use raw unrotated pdf.js page-view units; physical points = raw value × pages[].userUnit (or 1 when omitted), and pixels = raw value × UserUnit × render scale.

```bash
pdfvision document.pdf --render --render-output ./images --format json
```

--------------------------------

### Extract encrypted PDF with password and password-stdin

Source: https://pdfvision.dev/guide/usage

Use --password to pass the password directly, or --password-stdin to read it from standard input. Prefer --password-stdin to avoid exposing the password in shell history or process arguments.

```bash
pdfvision encrypted.pdf --password your-password --format json
```

```bash
printf "your-password\n" | pdfvision encrypted.pdf --password-stdin --format json
```

--------------------------------

### Inspect visual structure without rendering every full page

Source: https://pdfvision.dev/

Extracts layout, image boxes, vector boxes, and visual regions as JSON, then renders only the visual regions to an output directory.

```bash
npx pdfvision slides.pdf --layout --image-boxes --vector-boxes --visual-regions --json
npx pdfvision slides.pdf --render-visual-regions --render-output ./regions --json
```

--------------------------------

### Generate Markdown output with pdfvision

Source: https://pdfvision.dev/guide/output

Markdown is the default output format, optimized for conversational AI context. It includes an overview table, per-page sections, extracted text, layout table sections when --layout finds row-major table hints, search match tables, warnings, and image links when rendering is enabled. It deliberately omits rawText and --strip-repeated removes repeated layout blocks from the body.

```bash
pdfvision document.pdf
```

```bash
pdfvision document.pdf --format markdown
```

--------------------------------

### Run pdfvision with JSON output using --format json

Source: https://pdfvision.dev/guide

Runs pdfvision with JSON output, useful when another tool or agent will inspect the result programmatically. The JSON provides a machine-readable overview.

```bash
npx pdfvision document.pdf --format json
```

--------------------------------

### Render visual regions with --render-visual-regions

Source: https://pdfvision.dev/guide/rendering-and-ocr

Renders crop-ready regions for figures, charts, forms, tables, diagrams, and raster/vector clusters without rendering every full page. Use when the agent does not yet know the coordinates; pdfvision proposes visual regions from layout, image, vector, annotation, and form evidence.

```bash
pdfvision document.pdf --render-visual-regions --render-output ./regions --format json
```

--------------------------------

### Search for candidate evidence

Source: https://pdfvision.dev/guide/search-and-region-zoom

Run this command to locate candidate evidence without page bodies, returning results in JSON format.

```bash
pdfvision annual-report.pdf --search "Net sales" --search "Operating income" --matches-only --json
```

--------------------------------

### Run multiple search queries

Source: https://pdfvision.dev/guide/search-and-region-zoom

Executes multiple search queries in a single pass on the specified PDF file.

```bash
pdfvision paper.pdf --search "transformer" --search "attention" --json
```

--------------------------------

### Extract JSON from slide deck

Source: https://pdfvision.dev/guide

Practical default for a slide deck or visual report.

```bash
npx pdfvision deck.pdf --layout --image-boxes --vector-boxes --visual-regions --json
```

--------------------------------

### Probe outlines, page labels, and document features

Source: https://pdfvision.dev/guide/usage

Use this probe when the PDF viewer experience matters: page labels that differ from physical page numbers, bookmarks, open actions, optional content layers, or viewer preferences. Here -p 1 limits page extraction and emitted page output; it does not promise first-page-only document loading, parsing, or runtime. Without it, the feature flags still extract every page. Document-level fields still return. Page-level JavaScript actions are returned only for selected pages; when they matter, rerun --viewer with the relevant page range.

```bash
pdfvision document.pdf -p 1 --page-labels --outline --viewer --layers --format json
```

--------------------------------

### processFile

Source: https://pdfvision.dev/guide/library-api

Processes a PDF and returns the formatted string output in markdown, json, xml, or toon format, matching what the CLI prints. Useful when the formatted text itself is the integration boundary.

```APIDOC
## processFile

### Description
Processes a PDF document and returns the formatted string output that the CLI would print for the specified format (markdown, json, xml, or toon). This is useful for feeding formatted text into an LLM or consuming a standardized output string.

### Method
LibraryFunction

### Endpoint/Signature
processFile(filePath: string, options?: ProcessFileOptions): Promise<string>

### Parameters
- **filePath** (string) - Required - The path to the PDF file
- **options** (ProcessFileOptions) - Optional
  - **format** (string) - Optional - The output format: 'markdown', 'json', 'xml', or 'toon' (default 'markdown')
  - **pages** (string) - Optional - Page range selection, e.g. '1-2'
  - **noCache** (boolean) - Optional - Whether to bypass cache (default false)

### Response
Returns a string formatted according to the specified format.

### Example Response
```ts
const markdown = await processFile('./document.pdf', {
  format: 'markdown',
  pages: '1-2',
  noCache: false,
});
console.log(markdown);
```
```

--------------------------------

### Render visual regions for slide decks

Source: https://pdfvision.dev/guide/use-cases

Renders visual regions for slides containing large raster regions.

```bash
pdfvision deck.pdf --render-visual-regions --format json
```

--------------------------------

### Extract detailed signals for unknown PDFs

Source: https://pdfvision.dev/guide/use-cases

Add layout, image, vector, and visual region signals to the JSON output when the initial overview indicates complex content.

```bash
pdfvision document.pdf --layout --image-boxes --vector-boxes --visual-regions --json
```

--------------------------------

### Render a region with custom scale

Source: https://pdfvision.dev/guide/search-and-region-zoom

Applies a render scale to improve clarity for small text or dense elements within the specified region.

```bash
pdfvision report.pdf --pages 3 --render --render-region 120,180,360,140 --render-scale 3 --render-output ./crops --json
```

--------------------------------

### Scan multilingual documents with OCR

Source: https://pdfvision.dev/guide/use-cases

Specify multiple languages for OCR by listing the dominant language first.

```bash
pdfvision scan.pdf --ocr --ocr-lang jpn+eng --format json
```

--------------------------------

### Render one region with --render-region

Source: https://pdfvision.dev/guide/rendering-and-ocr

Renders a specific region of a page. The region is specified in raw unrotated page-view units with a top-left origin. The renderer applies UserUnit and render scale when producing pixels. Works after --search because search matches can carry bounding boxes.

```bash
pdfvision document.pdf --pages 2 --render --render-region 120,180,360,240 --render-output ./regions
```

--------------------------------

### Render specific visual regions

Source: https://pdfvision.dev/guide/use-cases

Render a specific crop of a document page based on identified coordinates.

```bash
pdfvision report.pdf --pages 8 --render --render-region 80,140,430,260 --render-output ./regions
```