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.

Published: 0.1.6 (10 September 2026). Atomic -o output and saved --idempotency-key recovery are available since 0.1.5. Version 0.1.6 corrects the package usage guidance. These examples pin the published version; shell redirection truncates its destination before conversion starts. Use -o document.md to preserve an existing destination if conversion fails.

Convert a local file

npx pdftomarkdown@0.1.6 document.pdf > document.md

Convert from a URL

npx pdftomarkdown@0.1.6 https://arxiv.org/pdf/1706.03762

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 (20 trial pages once for new accounts, full multi-page) is available via GitHub login:

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

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

Useful options

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

Output contract

Successful API JSON has complete: true; the CLI rejects an unmarked success instead of printing potentially partial Markdown. Canonical Markdown is never silently truncated. If a complete result exceeds the response budget, the CLI reports response_too_large on stderr; lower --max-pages or split the PDF.

Simple rectangular tables use escaped GFM pipe-table syntax. Complex tables with row or column spans, nested tables, or nested block content remain sanitized raw HTML inside the Markdown so their structure is preserved.

Timing

Allow up to 11 minutes for a synchronous request; measure elapsed time locally. Ctrl-C or timeout stops waiting, but processing and charging may continue. For paid recovery, save --idempotency-key and repeat the same command with identical document bytes and conversion options. Demo requests do not have the paid replay guarantee. Never retry uncertain paid work with a new identity automatically.

Exit codes

  • 0: success — markdown written to stdout.
  • 1: API, network, unreadable-file or incomplete-response error.
  • 2: usage error — bad flags or empty input.
  • 130: interrupted with Ctrl-C.

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