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:
autocpugpu
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.