PDF to Text Command line Reference

Conversion from PDF to text.

pdf2text [options] SOURCE
pdfcrowd pdf2text [options] SOURCE
pdf2text auth ACTION
pdf2text help [TOPIC|OPTION|CATEGORY]

Commands and Options

Conversion Input

SOURCE

Supply exactly one input source:

  • URL: an HTTP(S) URL.
  • File: the path to an existing local input file.
  • Standard input: - reads input bytes from a pipe or redirection.

Options may appear before or between sources. Use -- before a file name that starts with a dash.

Examples:
  • URL: pdf2text --output result.txt https://example.com/input.pdf
  • Local file: pdf2text --output result.txt input.pdf
  • Standard input: pdf2text --output result.txt - < input.pdf

Output

Results go to standard output by default. Binary output requires a file, pipe, or redirection; only pdf2text writes directly to a terminal. Some converters produce ZIP archives containing their results. Diagnostics use standard error.

--output, -o FILE

Save the result to FILE. Use - for standard output.

An existing output file is replaced only after a successful conversion.

To send binary results to standard output, redirect them to a file or pipe them to another program.

Default:
standard output
Example:
  • pdf2text --output FILE SOURCE

--print-page-count

Print page count to stderr after conversion.

Configuration

If the default configuration file exists, conversions read it automatically. Conversions never save settings automatically. Run pdf2text help configuration to see the default file path. --config and --no-config are mutually exclusive.

Use a UTF-8 INI file with option-name = value lines and no [section] headings. Use the option names with hyphens and without leading dashes, for example debug-log instead of --debug-log. Lines starting with # or ; are comments.

Inline values can span multiple lines when each continuation line is indented more than the setting name. A blank line ends the value. Use a separate file for content that needs blank lines or exact formatting.

--config PATH

Read conversion defaults from PATH instead of the default file.

Command-line options override the settings in this file. This option applies to conversion settings; credentials are stored separately.

Examples:
  • pdf2text --config PATH --output FILE SOURCE
  • pdf2text --config ./defaults.ini -o result SOURCE

--no-config

Ignore saved conversion defaults for this command.

Command-line conversion options still apply. Saved credentials and environment variables still apply. The config file is left unchanged.

Example:
  • pdf2text --no-config --output FILE SOURCE

--init-config

Create a commented config file that you can edit.

Open the created file and remove the leading # from settings you want to use. Future conversions read the default file automatically.

Use --config PATH to create a file at another location. An existing file is left unchanged. This command does not perform a conversion.

Examples:
  • pdf2text --init-config [--config PATH]
  • pdf2text --init-config
  • pdf2text --init-config --config ./defaults.ini

--show-config

Show saved defaults and command-line overrides without converting.

Each setting shows whether it came from the config file or the command line. Other options use their API defaults.

Sensitive values and inline HTML, CSS, and JavaScript are hidden. No files are changed.

Examples:
  • pdf2text --show-config [options]
  • pdf2text --show-config
  • pdf2text --no-config --show-config

Authentication

For account setup and credential selection, see Authentication.

auth ACTION

Manage credentials shared by all converter commands.

ACTION: Choose login, status, or logout.

Usage:
pdf2text auth ACTION
pdfcrowd auth ACTION

auth login [--non-interactive]

Save your PDFCrowd username and API key for all converter commands.

Use both credential environment variables when set; otherwise prompt in an interactive terminal. The API-key prompt hides your input.

In a script, use --non-interactive to require environment credentials without prompting. This saves the account; it does not perform a conversion.

Usage:
pdf2text auth login [--non-interactive]
pdfcrowd auth login [--non-interactive]
auth login --non-interactive

This option applies only to auth login.

Require environment credentials when saving an account with auth login; never prompt.

Set both PDFCROWD_USERNAME and PDFCROWD_API_KEY before running this command. The account is saved for all converters. Missing credentials cause an error.

Example:
  • pdf2text auth login --non-interactive

auth status

Show which credentials will be used without revealing the API key.

This reads local settings; it does not verify the account with PDFCrowd.

Usage:
pdf2text auth status
pdfcrowd auth status

auth logout

Remove the saved account for all converter commands.

Credential environment variables still apply when set.

Usage:
pdf2text auth logout
pdfcrowd auth logout

Help and Version

help [TOPIC|OPTION|CATEGORY]

Show offline help for this converter.

Help does not load saved settings or credentials and does not contact the service.

TOPIC|OPTION|CATEGORY: Omit the argument for an overview. Supply one topic, option name (with or without --), or conversion category ID.

  • all: List every option.
  • categories: List help topics and conversion option groups.
  • syntax: Explain how to supply arguments.
  • configuration: Save and load conversion defaults.
  • authentication: Set up your PDFCrowd account.
  • input-output: Read inputs and save results.
  • exit-codes: Check whether a command succeeded.
Usage:
pdf2text help [TOPIC|OPTION|CATEGORY]
pdfcrowd help pdf2text [TOPIC|OPTION|CATEGORY]
Examples:
  • pdf2text help all
  • pdf2text help categories
  • pdf2text help --output
help --json

This option applies only to help.

Print help as JSON for scripts, integrations, and AI agents.

Includes option names, argument types, defaults, allowed values, authentication rules, and exit codes. Works offline.

Example:
  • pdf2text help --json

--help, -h

Show a summary of commands and options.

Use help all for every option, or help OPTION for details.

Example:
  • pdf2text --help

--version, -V

Show the PDFCrowd CLI version.

Example:
  • pdf2text --version

General Options

--pdf-password

The password to open the encrypted PDF file.

Syntax:
--pdf-password PASSWORD

--print-page-range

Set the page range to print.

Syntax:
--print-page-range PAGES
Constraint:
  • A comma separated list of page numbers or ranges.
Examples:
  • Just the second page is printed: "2"
  • The first and the third page are printed: "1,3"
  • Everything except the first page is printed: "2-"
  • Just the first 3 pages are printed: "-3"
  • Pages 3, 6, 7, 8 and 9 are printed: "3,6-9"

--no-layout

Ignore the original PDF layout. Extract text in reading order without preserving column structure or positioning. Simpler output for pure text extraction.

Syntax:
--no-layout[=true|false]
Default:
false
Allowed Values:
  • true
  • false

--eol

The end-of-line convention for the text output.

Syntax:
--eol EOL
Default:
unix
Allowed Values:
  • unix — Unix convention "LF" is used.
  • dos — DOS convention "CR LF" is used.
  • mac — Mac convention "CR" is used.

--page-break-mode

Specify the page break mode for the text output.

Syntax:
--page-break-mode MODE
Default:
none
Allowed Values:
  • none — No page breaks are inserted.
  • default — The standard page break code "FF" is used.
  • custom — A custom page break is used. Set the separator with --custom-page-break.

--custom-page-break

Specify the custom page break.

Syntax:
--custom-page-break PAGE_BREAK
Examples:
  • Clear text between pages: "END OF PAGE"
  • Visual separator with line break 
    "----my page break----
"

--paragraph-mode

Specify the paragraph detection mode. Enable to format output with proper paragraph breaks. Use "none" for raw text, or detection modes for formatted output.

Syntax:
--paragraph-mode MODE
Default:
none
Allowed Values:
  • none — No paragraph detection.
  • bounding-box — Paragraph detection based on line bounding boxes.
  • characters — Paragraph detection based on the number of characters in the line.

--line-spacing-threshold

Set the maximum line spacing when the paragraph detection mode is enabled.

Syntax:
--line-spacing-threshold THRESHOLD
Constraint:
  • The value must be a positive integer percentage.
Default:
10%

--remove-hyphenation

Remove the hyphen character from the end of lines.

Syntax:
--remove-hyphenation[=true|false]
Default:
false
Allowed Values:
  • true
  • false

--remove-empty-lines

Remove empty lines from the text output.

Syntax:
--remove-empty-lines[=true|false]
Default:
false
Allowed Values:
  • true
  • false

--crop-area-x

Set the top left X coordinate of the crop area in points.

Syntax:
--crop-area-x X
Constraint:
  • Must be a positive integer or 0.
Example:
  • Start extraction at 1.4 inches from left: 100

--crop-area-y

Set the top left Y coordinate of the crop area in points.

Syntax:
--crop-area-y Y
Constraint:
  • Must be a positive integer or 0.
Example:
  • Start extraction at 1.4 inches from top: 100

--crop-area-width

Set the width of the crop area in points.

Syntax:
--crop-area-width WIDTH
Constraint:
  • Must be a positive integer or 0.
Default:
PDF page width.
Example:
  • Extract narrow 1.4 inch width: 100

--crop-area-height

Set the height of the crop area in points.

Syntax:
--crop-area-height HEIGHT
Constraint:
  • Must be a positive integer or 0.
Default:
PDF page height.
Example:
  • Extract small 1.4 inch height: 100

--crop-area

Set the crop area. It allows you to extract just a part of a PDF page.

Syntax:
--crop-area X Y WIDTH HEIGHT
Constraint:
  • Must be a positive integer or 0.
Constraint:
  • Must be a positive integer or 0.
Constraint:
  • Must be a positive integer or 0.
Constraint:
  • Must be a positive integer or 0.

Miscellaneous

--debug-log

Turn on debug logging to troubleshoot conversion issues. Details about the conversion process, including resource loading, rendering steps, and error messages are stored in the debug log. Use this when conversions fail or produce unexpected results.

Syntax:
--debug-log[=true|false]
Default:
false
Allowed Values:
  • true
  • false

--tag

Tag the conversion with a custom value for tracking and analytics. Use this to categorize conversions by customer ID, document type, or business unit. The tag appears in conversion statistics. A value longer than 32 characters is cut off.

Syntax:
--tag TAG
Example:
  • Track job in analytics: "client-1234"

--http-proxy

A proxy server used by the conversion process for accessing the source URLs with HTTP scheme. This can help circumvent regional restrictions or provide limited access to your intranet.

Syntax:
--http-proxy PROXY
Constraint:
  • The value must have format DOMAIN_OR_IP_ADDRESS:PORT.
Examples:
  • Corporate proxy server: "myproxy.com:8080"
  • Direct IP proxy connection: "113.25.84.10:33333"

--https-proxy

A proxy server used by the conversion process for accessing the source URLs with HTTPS scheme. This can help circumvent regional restrictions or provide limited access to your intranet.

Syntax:
--https-proxy PROXY
Constraint:
  • The value must have format DOMAIN_OR_IP_ADDRESS:PORT.
Examples:
  • Secure proxy for HTTPS: "myproxy.com:443"
  • Direct secure proxy IP: "113.25.84.10:44333"

API Client Options

--use-http

Specify whether to use HTTP or HTTPS when connecting to the PDFCrowd API.

Syntax:
--use-http[=true|false]
Default:
false
Allowed Values:
  • true
  • false

--client-user-agent

Specify the User-Agent HTTP header the CLI sends to the PDFCrowd API.

Syntax:
--client-user-agent AGENT
Default:
pdfcrowd_cli_client/1.1.0 (https://pdfcrowd.com)

--proxy

Specify an HTTP proxy the CLI uses to connect to the PDFCrowd API.

Syntax:
--proxy HOST PORT USER_NAME PASSWORD

--retry-count

Specify the number of automatic retries when a 502 or 503 HTTP status code is received. The status code indicates a temporary network issue. This feature can be disabled by setting to 0.

Syntax:
--retry-count COUNT
Default:
1
Example:
  • Retry failed requests three times: 3