---
title: "Nutrient PDF-to-Markdown CLI reference"
canonical_url: "https://www.nutrient.io/guides/dws-pdf-to-markdown/cli-reference/"
md_url: "https://www.nutrient.io/guides/dws-pdf-to-markdown/cli-reference.md"
last_updated: "2026-09-04T00:00:00.000Z"
description: "Commands, options, sign-in, local files, and exit behavior for PDF to Markdown."
---

# CLI reference

## Commands

| Command                          | Purpose                                                     |
| -------------------------------- | ----------------------------------------------------------- |
| `pdf-to-markdown INPUT [OUTPUT]` | Convert one PDF or a directory to Markdown.                 |
| `pdf-to-text INPUT [OUTPUT]`     | Convert one PDF or a directory to text.                     |
| `query text INPUT QUERY`         | Search an extracted file. This command is free.             |
| `nutrient auth login`            | Sign in through your browser.                               |
| `nutrient auth status`           | Show the current plan, Vision access, and unreported usage. |
| `nutrient auth logout`           | Report pending usage and sign out.                          |

Run any command with `--help` to see all of its options.

## Conversion options

| Option              | Purpose                                                         |
| ------------------- | --------------------------------------------------------------- |
| `--vision`          | Improve extraction for scans, handwriting, and complex layouts. |
| `--provider MODE`   | Choose automatic, CPU, or GPU processing for Vision.            |
| `--threads NUMBER`  | Set the number of files converted in parallel.                  |
| `--api-key KEY`     | Use a Nutrient API key.                                         |
| `--license-key KEY` | Use a Nutrient CLI license key.                                 |

`pdf-to-markdown` also accepts `--enable-image-export` to save extracted images next to the Markdown output.

`pdf-to-text --vision` writes structured JSON instead of plain text. Use `pdf-to-markdown --vision` when you want Markdown.

`--provider` accepts:

- `auto`

- `cpu`

- `gpu`

## Credentials

The CLI uses a Nutrient CLI license key first, then an API key, and then your saved Nutrient sign-in. Without any of these, Standard still works and Vision asks you to sign in.

For automation, set `NUTRIENT_API_KEY` instead of passing `--api-key`. An invalid key or expired sign-in is reported as an error; the CLI doesn’t quietly switch to another account.

## Local files

Configuration is stored in:

- macOS: `~/.config/nutrient/cli/`

- Linux: `${XDG_CONFIG_HOME:-~/.config}/nutrient/cli/`

- Windows: `%APPDATA%\nutrient\cli\`

Usage waiting to be reported is stored in your operating system’s application-data directory. Account credentials are stored in Keychain on macOS, Credential Manager on Windows, or Secret Service on Linux.

If secure storage is unavailable, the CLI can store the automatic credential used to report Standard usage in a local file readable only by your user account on macOS or Linux. On Linux, it can also do this for a signed-in account after asking first.

The CLI creates a one-way identifier for the installation. It never sends the system details used to create the identifier. The identifier can’t reveal those details or restore a lost sign-in.

## Sign-in behavior

`nutrient auth login` connects the CLI to the account approved in your browser.

`nutrient auth logout` reports pending account usage before removing the saved sign-in.

## Usage and privacy

Standard conversion is free. Each input page uses one Vision page from your monthly allowance. Failed conversions and `query` don’t use Vision pages.

Usage reports include a random event ID, the command, Standard or Vision mode, input page count, time, and CLI version. They don’t include file names, paths, document contents, or output.

## Offline behavior

Standard can continue when Nutrient is unavailable. Vision permission lasts for one hour and allows up to 100 pages before the CLI must reconnect. The document that crosses the threshold can finish.

## Exit codes

Successful commands exit with status `0`. Invalid arguments, authentication errors, and conversion failures exit with a nonzero status. The CLI doesn’t modify the input file.

If Nutrient Support asks for connection details, add `-t` or `--trace` to an auth or conversion command. Trace output omits credentials and request bodies.

---

## Related pages

- [PDF to Markdown](/guides/dws-pdf-to-markdown.md)
- [Get started](/guides/dws-pdf-to-markdown/getting-started.md)