Commands
Use these commands to convert files, search output, and manage authentication.
| 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 list its options.
Conversion options
Use these options to choose the conversion mode and authentication method.
| 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 need Markdown.
--provider accepts these values:
autocpugpu
Credentials
The CLI checks credentials in this order: Nutrient CLI license key, API key, saved Nutrient sign-in. Without credentials, standard conversion still works and Vision asks you to sign in.
For automation, set NUTRIENT_API_KEY instead of passing --api-key. The CLI reports an invalid key or expired sign-in as an error and doesn’t switch to another account.
Local files
The CLI stores configuration in these locations:
- macOS:
~/.config/nutrient/cli/ - Linux:
${XDG_CONFIG_HOME:-~/.config}/nutrient/cli/ - Windows:
%APPDATA%\nutrient\cli\
The CLI keeps pending usage reports on your computer and sends them the next time it runs online with the same sign-in or API key.
The CLI stores account credentials 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 for standard usage reports in a local file. Only your user account can read that file on macOS or Linux. On Linux, the CLI can also store a signed-in account this way 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 status shows your plan and sends pending usage to Nutrient. It uses NUTRIENT_API_KEY if that variable is set, or your saved sign-in if not. It doesn’t accept --api-key.
nutrient auth logout reports pending account usage before removing the saved sign-in. If it can’t report that usage — for example, because you’re offline — the sign-out fails and you stay signed 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, the mode, the input page count, the time, and the CLI version. They don’t include file names, paths, document contents, or output.
Offline behavior
What works offline depends on the conversion mode and the credential:
- Standard without an API key — Works offline, whether or not you’re signed in.
- Standard with an API key — Works offline for up to an hour after the CLI last confirmed the key. After that, conversion doesn’t start until Nutrient confirms the key again.
- Vision with a sign-in or API key — Works offline for up to an hour after the CLI’s last check-in. The CLI checks in with Nutrient each time it reports Vision usage. Offline, a new document needs two things. Enough Vision pages must remain to cover it, and fewer than 100 Vision pages must be waiting to be reported.
- Nutrient CLI license key — Works offline. The CLI never contacts Nutrient for licensing or usage reporting.
Once a document starts, it finishes, even if it runs past the hour or the 100-page limit. The first Vision conversion downloads about 1 GB of models and requires a connection, even with a license key.
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.
With an API key, a Vision command also exits with a nonzero status when it can’t confirm its usage with Nutrient. The CLI still writes the output and keeps the usage record to report later.
If Nutrient Support asks for connection details, add -t or --trace to an authentication or conversion command. Trace output omits credentials and request bodies.