CLI — PDF to Markdown from the terminal

Convert PDFs to Markdown in one command with npx pdftomarkdown. No install, no code — local files, URLs, or stdin.

The official CLI wraps the pdfToMarkdown API in a single command. It needs Node 18+ and nothing else — npx fetches it on demand. Markdown goes to stdout, so it is safe to pipe; status and errors go to stderr.

Convert a local file

npx pdftomarkdown document.pdf > document.md

Convert from a URL

npx pdftomarkdown https://arxiv.org/pdf/1706.03762 -o attention.md

Use your API key

Without a key the CLI uses the public demo tier: page 1 only, 3 requests per minute per IP, watermark in the output. A free Developer key (100 pages/month, full multi-page) takes 30 seconds via GitHub login:

export PDFTOMARKDOWN_API_KEY=your_key_here
npx pdftomarkdown document.pdf > document.md

You can also pass --key explicitly; it takes precedence over the environment variable.

Useful options

npx pdftomarkdown invoice.pdf --max-pages 1   # bound latency and quota
npx pdftomarkdown document.pdf --json          # full JSON response instead of markdown
cat document.pdf | npx pdftomarkdown - -o out.md   # read from stdin
npx pdftomarkdown --help                       # all options

Timing

A GPU performs real OCR at roughly 10–30 seconds per page, and the first request after a quiet period can add a cold-start wait of a minute or more. The CLI waits up to 11 minutes — don't ctrl-C.

Exit codes

  • 0: success — markdown written to stdout or the -o file.
  • 1: API error — the message on stderr states the fix.
  • 2: usage error — bad flags or unreadable input.

Claude Code plugin

If you use Claude Code, install the official plugin and Claude runs this CLI automatically whenever a task involves a PDF ("summarize this PDF", "extract the table from invoice.pdf"):

/plugin marketplace add ThiloReintjes/pdftomarkdown-skill
/plugin install pdftomarkdown@pdftomarkdown

Setup guides for other agents: Claude Code · Codex · Cursor.

Links

npm package · API docs · OpenAPI spec