pdfvision

https://github.com/yamadashy/pdfvision
Admin
pdfvision is a CLI tool, MCP server, and TypeScript library that extracts text, metadata, layout,...
Tokens:92,573
Snippets:659
Trust Score:9.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Verify installation

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/installation.md

Check the installed version and verify functionality with a test extraction.

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

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

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

### Install pdfvision globally

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/installation.md

Install the package globally to enable the pdfvision command in any shell.

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

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

### Install without OCR dependencies

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/installation.md

Install the package while omitting optional OCR dependencies to reduce footprint.

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

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

### Install Agent Skills

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/agent-skill.md

Add the pdfvision agent skills to your project using npx.

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

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

### TOON output format example

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/formats.md

An example of the TOON format showing YAML-style indentation, tabularized arrays with headers, and nested object folding.

```text
file: /path/doc.pdf
totalPages: 14
metadata:
  title: ...
overview[2]:
  - page: 1
    charCount: 40
    quality:
      nativeTextStatus: ok
    width: 612
    height: 792
  - page: 2
    ...
pages[2]:
  - page: 1
    text: "line one\nline two"
    charCount: 40
    spans[2]{text,x,y,width,height,fontSize,fontName}:
      pdfvision headers fixture,50,27.18,108.38,10,10,font1
      Body of page 1,50,194.36,134.54,20,20,font1
    layout:
      blocks[2]:
        - text: ...
          lines[1]{text,x,y,width,height,fontSize}:
            ...
```

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

### Install pdfvision as a library

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/installation.md

Add pdfvision as a project dependency and import the processDocument API.

```bash
npm install pdfvision
```

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

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

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

### Common starting point commands

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/index.md

Practical default commands for various document types including research papers, slide decks, and forms.

```bash
npx pdfvision document.pdf --json
npx pdfvision paper.pdf --layout --image-boxes --json
npx pdfvision deck.pdf --layout --image-boxes --vector-boxes --visual-regions --json
npx pdfvision scan.pdf --ocr --ocr-lang eng --json
npx pdfvision form.pdf --layout --form-fields --annotations --links --json
npx pdfvision report.pdf --search "term" --json
npx pdfvision report.pdf --pages 2 --render --render-region 120,180,360,140 --render-output ./crops --json
```

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

### pdfvision docs [topic]

Source: https://github.com/yamadashy/pdfvision/blob/main/README.md

Displays documentation for the installed version of pdfvision.

```APIDOC
## pdfvision docs [topic]

### Description
Provides documentation for the installed version. Running without a topic lists available topics.
```

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

### Install Agent Skills globally

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/agent-skill.md

Add the pdfvision agent skills globally using the -g flag.

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

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

### Conventional Commits Examples

Source: https://github.com/yamadashy/pdfvision/blob/main/CLAUDE.md

Examples of commit messages following the Conventional Commits specification with module scopes.

```text
feat(renderer): add per-page PNG output
fix(processor): handle encrypted PDF gracefully
refactor(cli): split help text into its own module
docs(readme): add multimodal usage section
test(pageRange): cover comma + range mix
chore(deps): bump pdfjs-dist to v5.6
```

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

### Install pdfvision agent skill

Source: https://github.com/yamadashy/pdfvision/blob/main/README.md

Add the pdfvision skill to your project or global environment to enable agentic tool usage.

```bash
# Project install (default) — drops the skill into <cwd>/.claude/skills/pdfvision/
npx skills add yamadashy/pdfvision

# Global install — drops it into ~/.claude/skills/pdfvision/ instead
npx skills add yamadashy/pdfvision -g
```

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

### Run pdfvision CLI for unknown PDF

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/index.md

Use this command as a starting point for processing an unknown PDF document.

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

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

### pdfvision CLI Usage Examples

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/options.md

Common command-line patterns for processing PDF documents, including extraction, rendering, searching, and OCR.

```text
  pdfvision document.pdf                                                       # markdown to stdout
  pdfvision report.pdf --map                                                   # what the document is, no page bodies (first move on a long PDF)
  pdfvision document.pdf --json                                                # JSON shortcut
  pdfvision document.pdf -p 1-3 --json                                         # specific pages, JSON
  pdfvision document.pdf -r --render-output ./images                           # render PNGs to ./images
  pdfvision slides.pdf -r --render-scale 1                                     # 1× raster (smaller PNGs)
  pdfvision report.pdf -p 3 -r --render-region 100,200,300,150                 # zoom into a 300×150 page-view-unit box on page 3
  pdfvision report.pdf --search "revenue" --json                               # find emitted "revenue" matches with bboxes; pipe to --render-region
  pdfvision paper.pdf --search "GPT" --search "transformer" --json             # multi-query (each match keeps its source query)
  pdfvision paper.pdf --search "BLEU" --matches-only                           # report metadata + flat match list, without page bodies
  pdfvision report.pdf -p 3-5 -r --render-output ./images --geometry --json    # PNGs + spans for 3-5
  pdfvision slides.pdf --xml --geometry                                        # layout / geometry as XML
  pdfvision report.pdf --toon --geometry                                       # geometry spans in TOON format
  pdfvision report.pdf --layout --strip-repeated                               # markdown w/o repeated chrome
  pdfvision encrypted.pdf --password "secret" --json                           # encrypted PDF
  printf "secret\n" | pdfvision encrypted.pdf --password-stdin --json          # avoid password in argv
  pdfvision scan.pdf --ocr --json                                              # OCR a scanned PDF
  pdfvision scan-ja.pdf --ocr --ocr-lang jpn+eng --json                        # multi-lang OCR
  pdfvision --remote https://example.com/paper.pdf --json                      # fetch + extract JSON
  pdfvision clear-cache                                                        # clear the verified pdfvision cache
  pdfvision docs                                                               # list the built-in documentation topics
  pdfvision docs warnings                                                      # read one topic
```

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

### pdfvision mcp

Source: https://github.com/yamadashy/pdfvision/blob/main/README.md

Starts the pdfvision server over the Model Context Protocol.

```APIDOC
## pdfvision mcp

### Description
Serves pdfvision over the Model Context Protocol on stdio for integration with AI hosts.
```

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

### Configure OCR languages with --ocr-lang

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/ocr.md

Examples of using the --ocr-lang flag with single or multiple language codes joined by plus signs. Note that the order of languages affects OCR output and runtime.

```bash
npx pdfvision doc.pdf --ocr --ocr-lang eng         # English only (default)
npx pdfvision doc.pdf --ocr --ocr-lang eng+jpn     # English + Japanese
npx pdfvision doc.pdf --ocr --ocr-lang chi_sim     # Simplified Chinese
npx pdfvision doc.pdf --ocr --ocr-lang eng+chi_sim+chi_tra
```

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

### Get formatted output with processFile

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/library-api.md

Returns formatted text output such as Markdown, XML, or TOON, suitable for feeding directly into an LLM context window.

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

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

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

### Run project verification commands

Source: https://github.com/yamadashy/pdfvision/blob/main/CLAUDE.md

Execute the full suite of linting, testing, and build commands to verify the project state before finalizing work.

```bash
npm run lint
npm run test
npm run build
```

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

### Acquire sample PDFs via curl

Source: https://github.com/yamadashy/pdfvision/blob/main/tests/agent-regression/README.md

Commands to download sample PDF files with stable public URLs for testing purposes.

```bash
curl -L https://www.soumu.go.jp/main_content/001019264.pdf -o soumu-r7-summary.pdf
curl -L -r 0-131071 https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-63-3.pdf -o truncated.pdf
curl -L https://raw.githubusercontent.com/mozilla/pdf.js/master/test/pdfs/xfa_filled_imm1344e.pdf -o xfa-form.pdf
```

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

### pdfvision CLI Help and Usage

Source: https://github.com/yamadashy/pdfvision/blob/main/README.md

Displays the command-line interface help, including common usage patterns, available options, and subcommands for extracting data from PDF files.

```text
pdfvision - Extract text, images, metadata, and layout from PDF files for AI agents

Command shape: options are for reading a PDF; anything else is a subcommand.
(--help and --version are the usual exceptions, and work anywhere.)

Usage:
  pdfvision <file.pdf> [options]
  pdfvision --remote <url> [options]
  pdfvision docs [topic]
  pdfvision clear-cache
  pdfvision mcp

Common flows
  pdfvision doc.pdf                     Read it. Per-page quality and warnings name the next flag
                                        when the default pass is not enough.
  pdfvision report.pdf --map            What the document is, no page bodies. The first move on a
                                        long or unfamiliar PDF.
  pdfvision doc.pdf --search "term" --matches-only
                                        Locate a term without reading the whole body; each match
                                        reports its page, bbox, and a crop-ready region.
  pdfvision doc.pdf -p <page> -r --render-region <x,y,w,h>
                                        Crop that region as image evidence (a match's region, or
                                        a layout block's bbox when there is no term to search).
  pdfvision doc.pdf -p <pages> --ocr    Re-read scanned pages (quality: empty_but_visual_content).

Options
  Every option, with its interactions and caveats: pdfvision docs options

  -p, --pages <range>     Pages to extract: "1", "1-5", "1,3,5", "2-4,7". Default: all pages.
  -f, --format <type>     markdown (default), json, xml, toon. Also --markdown / --json /
                          --xml / --toon.
  -r, --render            Render each selected page to a PNG and report its path.
      --render-output <dir>   Where the PNGs land. Requires --render or --render-visual-regions.
      --render-scale <n>      Rasterisation multiplier, default 2 (≈144 DPI); bounds (0, 4].
                              Requires --render, --render-visual-regions, or --ocr.
      --render-region <x,y,width,height>
                          Crop one page in raw page-view units. Single-page only.
      --map               A map of the document instead of its contents: pages, metadata,
                          outline, per-page quality and warning codes. Markdown only.
      --search <query>    Find <query> and report each hit's page and bbox. Repeatable.
      --matches-only      Report matches plus compact diagnostics, with crop-ready regions. Needs --search.
      --search-regex, --search-case-sensitive
                          Regex instead of literal substring; exact case.
      --ocr               OCR the selected pages beside the native text. Slow; opt-in.
      --ocr-lang <lang>   Language(s) for --ocr, plus-separated (e.g. `eng+jpn`). Default: eng.
      --layout            Reconstruct lines, blocks, vertical CJK stacks, and table hints.
      --visual-regions, --render-visual-regions
                          Crop-ready bboxes for figures, charts, tables, forms — and their PNGs.
      --form-fields, --links, --annotations
                          Interactive widgets; link targets; comments, highlights, stamps, ink.
      --outline, --page-labels, --attachments, --attachment-output <dir>
                          Bookmarks; viewer page labels; embedded files, and where to write them.
      --geometry, --image-boxes, --vector-boxes
                          Per-text-item, raster, and vector bounding boxes. Structured formats only.
      --structure, --viewer, --layers
                          Tagged-PDF structure; viewer/JavaScript settings; optional content groups.
      --strip-repeated    Drop running headers / footers from the Markdown body. Requires --layout.
      --password <value>, --password-stdin
                          Open an encrypted PDF. The password is never emitted in output.
      --remote <url>      Download an http(s) PDF and extract it.
      --no-cache          Re-download and re-extract instead of reusing the cache.
      --no-normalize      Keep the pre-NFKC text as well.
      --clear-cache       Deprecated alias for the clear-cache subcommand; removed in v1.0.
  -v, --version           Show version
  -h, --help              Show this help

Subcommands
  docs [topic]            Documentation for the installed version. Bare `docs` lists topics.
  clear-cache             Remove cached extractions, renders, remote PDFs, and OCR data.
  mcp                     Serve pdfvision over the Model Context Protocol on stdio, for hosts
                          that cannot run a shell. See "pdfvision mcp --help".
  A subcommand is recognized only as the first argument, so a file named `docs`, `mcp`, or
  `clear-cache` must be passed as `./docs` and so on.
```

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

### Check pdfvision version

Source: https://github.com/yamadashy/pdfvision/blob/main/skills/pdfvision/SKILL.md

Verify the installed version of pdfvision. Requires Node.js >= 22.13.

```bash
npx pdfvision --version   # Node.js >= 22.13; `npm i -g pdfvision` if used a lot
```

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

### Render full pages with CLI

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/rendering-and-ocr.md

Renders all pages of a PDF to images in the specified output directory.

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

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

### Zoom into a specific region

Source: https://github.com/yamadashy/pdfvision/blob/main/skills/pdfvision/SKILL.md

Re-run the command with specific page and region coordinates to get a cropped PNG of a suspicious or flagged block.

```bash
--pages <N> --render --render-region <x,y,w,h>
```

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

### Find-then-zoom Workflow

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/search.md

A two-step process using --matches-only to identify a match and then render the specific region.

```bash
pdfvision doc.pdf --search "revenue" --matches-only --json
# pick a match m from matches[*]
pdfvision doc.pdf -p <m.page> --render --render-region <m.region.x>,<m.region.y>,<m.region.width>,<m.region.height>
```

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

### Missing dependency error message

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/ocr.md

The error message displayed when the --ocr flag is used without the required tesseract.js dependency installed.

```text
--ocr requires the optional dependency "tesseract.js" (not installed).
Install it with: npm install tesseract.js
```

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

### XML output structure example

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/formats.md

A representative XML document structure showing the hierarchy of metadata, overview, and page-level content including spans, layout blocks, and OCR data.

```xml
<document file="..." totalPages="14" javascriptActionCount="..." outlineCount="..." xfa="true">
  <metadata>
    <title>...</title>
    <author>...</author>
  </metadata>
  <overview>
    <page no="1" label="i" charCount="..." imageCount="..." vectorCount="..." textCoverage="..." nonPrintableRatio="..." nonPrintableCount="..." nativeTextStatus="..." visualStatus="..." userUnit="2" width="..." height="..."/>
    ...
  </overview>
  <pages>
    <page no="1" label="i" charCount="..." imageCount="..." vectorCount="..." textCoverage="..." nonPrintableRatio="..." nonPrintableCount="..." formFieldCount="..." linkCount="..." annotationCount="..." nativeTextStatus="..." visualStatus="..." rotation="90" userUnit="2" width="..." height="..." image="...">
      <spans>
        <span text="..." x="..." y="..." width="..." height="..." fontSize="..." fontName="..."/>
        ...
      </spans>
      <layout>
        <block x="..." y="..." width="..." height="..." role="heading" repeated="true">
          <line x="..." y="..." width="..." height="..." fontSize="...">...</line>
          ...
        </block>
        ...
      </layout>
      <imageBoxes>
        <imageBox x="..." y="..." width="..." height="..."/>
        ...
      </imageBoxes>
      <vectorBoxes>
        <vectorBox x="..." y="..." width="..." height="..."/>
        ...
      </vectorBoxes>
      <text>
...page text body...
      </text>
      <rawText>
...pre-normalization text, when normalization changed it...
      </rawText>
      <ocr lang="eng" confidence="0.91">
        <text>
...OCR text...
        </text>
        <words>
          <word text="..." confidence="..." x="..." y="..." width="..." height="..."/>
          ...
        </words>
      </ocr>
    </page>
    ...
  </pages>
</document>
```

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

### Advanced search with regex and case sensitivity

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/search-and-region-zoom.md

Demonstrates using regex for pattern matching and case-sensitive search flags.

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

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

### Render crop from search results

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/src/en/guide/use-cases.md

Use bounding box information from search results to render a specific region for verification.

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

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

### Configure MCP server in JSON

Source: https://github.com/yamadashy/pdfvision/blob/main/docs/cli-topics/mcp.md

Add this configuration to your MCP host settings to enable the pdfvision server via npx.

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