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 stores pending usage reports in your operating system’s application-data directory. It 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 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, 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
Standard conversion can continue when Nutrient is unavailable. Vision permission lasts for one hour and enables 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 authentication or conversion command. Trace output omits credentials and request bodies.