Get started

Install the CLI

Install the CLI from npm:

npm install -g @pspdfkit/pdf-to-markdown

Use the shell installer as an alternative:

curl -fsSL \
  https://raw.githubusercontent.com/PSPDFKit/pdf-to-markdown/main/install.sh \
  | sh

The CLI supports macOS 13 or newer on Apple Silicon, Linux with glibc 2.38 or newer, and Windows. Linux also needs libcurl 4, ICU, and OpenSSL 3. On a minimal Ubuntu 24.04 image, install these packages with apt-get install libcurl4t64 libicu74 ca-certificates. On Windows, run shell commands in Git Bash.

Check the installation:

nutrient --version

Convert a PDF

Standard conversion is free and doesn’t require an account. Run this command to convert a PDF:

pdf-to-markdown input.pdf output.md

The conversion runs on your computer, and the CLI doesn’t upload your PDF or Markdown output to Nutrient.

Sign in for Vision

Run this command to sign in:

nutrient auth login

The CLI opens a Nutrient page in your browser. Approve the request. Then return to your terminal.

Check your plan and remaining Vision pages:

nutrient auth status

Use Vision

Vision improves extraction for scans, handwriting, formulas, and complex tables. Run this command to use Vision:

pdf-to-markdown --vision scan.pdf scan.md

Each input page uses one Vision page from your monthly allowance, but failed conversions don’t use Vision pages.

The first Vision conversion downloads about 1 GB of models, so it requires a connection. Later conversions use the copy stored on your computer.

Use an API key in CI

Standard conversion works in containers and continuous integration (CI) without an account. To use Vision, create a live API key in the PDF-to-Markdown dashboard(opens in a new tab). Then set the key as an environment variable:

export NUTRIENT_API_KEY="pdf_live_..."
pdf-to-markdown --vision input.pdf output.md

You can also use --api-key, but environment variables are safer because command arguments can appear in shell history and process listings.

Test keys work for standard conversion but not for Vision. When you use a live or test key, the CLI also confirms it with Nutrient before standard conversion. To run standard steps without a connection, set the key only for the steps that use Vision.

With an API key, each Vision command waits up to 30 seconds for Nutrient to confirm its usage. If Nutrient doesn’t confirm it, the command still writes the output but exits with a nonzero status, so the CI step fails.

Work offline

Without an API key, standard conversion works offline, whether or not you’re signed in. With an API key, the CLI confirms the key with Nutrient and reuses that check for up to an hour. After that, standard conversion doesn’t start until Nutrient confirms the key again.

With a sign-in or API key, Vision works offline for up to an hour after the CLI last checked in with Nutrient. While online, the CLI checks in each time it reports Vision usage. Offline, Vision starts a new document only if both of these are true:

• Your remaining Vision pages cover the whole document.
• Fewer than 100 Vision pages are waiting to be reported.

Once a document starts, it finishes, even if it runs past the hour or the 100-page limit. With an API key, an offline Vision command still writes its output but exits with a nonzero status. The CLI reports pending usage the next time it runs online with the same sign-in or API key. nutrient auth status also sends pending usage, using NUTRIENT_API_KEY or your saved sign-in.

Existing --license-key workflows never contact Nutrient for licensing or usage reporting and continue to work offline.