Rules for agents

• Convert each PDF once and save the result. Search the saved file instead of converting it again.
• For a known term, start with a bounded search such as grep -n -i -C2 "term" file | head.
• Use the query skill when you do not know the exact wording or a plain search returns too many matches.
• Use pdf-to-markdown when headings, lists, and tables matter more than whitespace and column alignment.
• Do not render PDF pages as images to extract selectable text. Use Vision for scans and image-only PDFs.

PDF to Text

Convert PDFs to plain text while preserving columns, indentation, and table alignment.

Related skills

• pdf-to-markdown — preserves headings, lists, tables, and reading order as Markdown.
• query — searches a large converted file and returns only the most relevant passages.

Usage

Set SKILL_DIR to the absolute path of the directory containing this file. Use $SKILL_DIR/bin/pdf-to-text in the commands below.

The wrapper downloads the CLI from Nutrient's CDN on first use and stores it in ~/.local/share/nutrient/cli/. It checks for updates every six hours.

Convert one PDF

$SKILL_DIR/bin/pdf-to-text INPUT.pdf OUTPUT.txt

Omit OUTPUT.txt to write text to stdout.

Convert several PDFs

For two or more PDFs, pass an input directory and an output directory. The CLI converts the files in parallel.

$SKILL_DIR/bin/pdf-to-text INPUT_DIR/ OUTPUT_DIR/

Use Vision

Vision handles scans, photographs, handwriting, formulas, and complex layouts. With pdf-to-text, Vision writes structured JSON rather than plain text. Use pdf-to-markdown --vision when you want Markdown.

$SKILL_DIR/bin/pdf-to-text --vision INPUT.pdf OUTPUT.json

Standard conversion is free and does not require an account. Vision requires a Nutrient account, API key, or Nutrient CLI license key. With an account or API key, each input page uses one Vision page from the account's monthly allowance. Nutrient CLI license keys keep their existing terms. Failed conversions do not use Vision pages.

If Vision asks for an account, show that message to the user and ask them to run:

$SKILL_DIR/bin/nutrient auth login

Do not start sign-in automatically. Do not retry Vision without authentication.

For unattended use, the user can set NUTRIENT_API_KEY. Never ask the user to paste a key into chat or put it directly in a command.

Account commands

$SKILL_DIR/bin/nutrient auth login
$SKILL_DIR/bin/nutrient auth status
$SKILL_DIR/bin/nutrient auth logout

status shows the current plan, Vision access, and usage waiting to be reported. Never sign out or switch accounts unless the user asks.

Workflow

1. Choose Standard or Vision. Start with Standard unless the PDF is scanned or image-only.
2. Convert the PDF once and check the exit code. Exit 0 means success.
3. Check that the output exists and is not empty.
4. Tell the user where the output was saved.
5. Do not read a large output file back into context unless the user wants it analyzed. Search it with bounded grep or the query skill instead.

Offline behavior

Standard can continue when Nutrient is unavailable. After Vision connects, it can work offline for one hour and process up to 100 pages before it must reconnect. A document that crosses the 100-page threshold can finish.

Troubleshooting

• Empty or minimal output: The PDF may be scanned or image-only. Offer Vision.
• Vision asks for sign-in: Show the CLI message and ask the user to run $SKILL_DIR/bin/nutrient auth login. Do not retry first.
• No Vision pages remain: Show the CLI message and the pricing page. Do not retry or change account state.
• Credential error during Standard conversion: An explicitly configured key or saved sign-in is invalid. Show the error. Do not remove or replace credentials unless the user asks.
• First run is slow: The wrapper downloads the platform binary once. Later runs use the cached copy.
• Columns look wrong: Try pdf-to-markdown if headings, lists, and tables matter more than exact spacing.
• Other nonzero exit: Read stderr and report the specific error. Common causes include a damaged PDF, unsupported encryption, or a first-run download failure.

Plans and licensing

Standard conversion is free. With an account or API key, Vision uses the account's monthly allowance. Nutrient CLI license keys keep their existing terms. See current plans.

Use is subject to the Nutrient PDF to Markdown License and Nutrient's Privacy Policy. Redistribution, OEM, embedded, and white-label use require a separate agreement with Nutrient.