Image to Image Command line Reference

Conversion from one image format to another image format.

image2image [options] SOURCE
pdfcrowd image2image [options] SOURCE
image2image auth ACTION
image2image 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: image2image --output result.png https://example.com/input.png
  • Local file: image2image --output result.png input.png
  • Standard input: image2image --output result.png - < input.png

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:
  • image2image --output FILE SOURCE

Configuration

If the default configuration file exists, conversions read it automatically. Conversions never save settings automatically. Run image2image 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:
  • image2image --config PATH --output FILE SOURCE
  • image2image --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:
  • image2image --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:
  • image2image --init-config [--config PATH]
  • image2image --init-config
  • image2image --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:
  • image2image --show-config [options]
  • image2image --show-config
  • image2image --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:
image2image 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:
image2image 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:
  • image2image 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:
image2image auth status
pdfcrowd auth status

auth logout

Remove the saved account for all converter commands.

Credential environment variables still apply when set.

Usage:
image2image 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:
image2image help [TOPIC|OPTION|CATEGORY]
pdfcrowd help image2image [TOPIC|OPTION|CATEGORY]
Examples:
  • image2image help all
  • image2image help categories
  • image2image 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:
  • image2image help --json

--help, -h

Show a summary of commands and options.

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

Example:
  • image2image --help

--version, -V

Show the PDFCrowd CLI version.

Example:
  • image2image --version

Conversion Format

--output-format

The output file format.

Syntax:
--output-format OUTPUT_FORMAT
Default:
png
Allowed Values:
  • png
  • jpg
  • gif
  • tiff
  • bmp
  • ico
  • ppm
  • pgm
  • pbm
  • pnm
  • psb
  • pct
  • ras
  • tga
  • sgi
  • sun
  • webp

Image Operations

--resize

Scale the image to different dimensions. Accepts percentage values for proportional scaling or explicit pixel dimensions for absolute sizing.

Syntax:
--resize RESIZE
Default:
100%
Examples:
  • Enlarge for high-res display: "200%"
  • Standard XGA screen resolution: "1024x768"

--rotate

Rotate the image by the specified angle in degrees. Positive values rotate clockwise, negative values counterclockwise.

Syntax:
--rotate ROTATE

--crop-area-x

Set the horizontal starting position of the crop area, measured from the left edge of the print area. Positive values offset inward from the left edge, negative values extend beyond the left boundary.

Syntax:
--crop-area-x X
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Default:
0px
Examples:
  • Crop extends beyond left edge: "-1in"
  • Skip narrow border area: "10mm"

--crop-area-y

Set the vertical starting position of the crop area, measured from the top edge of the print area. Positive values offset inward from the top edge, negative values extend beyond the top boundary.

Syntax:
--crop-area-y Y
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Default:
0px
Examples:
  • Crop extends beyond top edge: "-1in"
  • Skip narrow border area: "10mm"

--crop-area-width

Set the horizontal extent of the crop area. Defines the width of the region to be converted. Minimum value is 1 inch.

Syntax:
--crop-area-width WIDTH
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Default:
The width of the print area.
Examples:
  • Standard document crop width: "8in"
  • Full A4 page width crop: "210mm"

--crop-area-height

Set the vertical extent of the crop area. Defines the height of the region to be converted. Minimum value is 1 inch.

Syntax:
--crop-area-height HEIGHT
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Default:
The height of the print area.
Examples:
  • Standard US Letter crop height: "11in"
  • Full A4 page height crop: "297mm"

--crop-area

Define a rectangular region to convert by setting X/Y position and width/height simultaneously. Coordinates are relative to the print area's top-left corner.

Syntax:
--crop-area X Y WIDTH HEIGHT
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.

--remove-borders

Detect and remove solid-color borders surrounding the image content. Only removes borders that consist of a single consistent color.

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

Canvas Setup

--canvas-size

Set the output canvas size. Use standard sizes (A4, Letter, A3, etc.) for printable output with consistent dimensions.

Syntax:
--canvas-size SIZE
Allowed Values:
  • A0
  • A1
  • A2
  • A3
  • A4
  • A5
  • A6
  • Letter

--canvas-width

Set the output canvas width.

Syntax:
--canvas-width WIDTH
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Examples:
  • A4 landscape / banner width: "297mm"
  • US Letter standard width: "8.5in"

--canvas-height

Set the output canvas height.

Syntax:
--canvas-height HEIGHT
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Examples:
  • Large poster canvas height: "420mm"
  • US Letter standard height: "11in"

--canvas-dimensions

Set the output canvas dimensions. If no canvas size is specified, margins are applied as a border around the image.

Syntax:
--canvas-dimensions WIDTH HEIGHT
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Examples:
  • A4 portrait dimensions: "210mm", "297mm"
  • US Letter dimensions: "8.5in", "11in"
  • A3 portrait dimensions: "297mm", "420mm"

--orientation

Set the output canvas orientation. Use portrait for vertical content, landscape for horizontal or wide content.

Syntax:
--orientation ORIENTATION
Default:
portrait
Allowed Values:
  • landscape
  • portrait

--position

Set the image position on the canvas. Center for balanced composition, or corner/edge positions for specific layouts.

Syntax:
--position POSITION
Default:
center
Allowed Values:
  • center
  • top
  • bottom
  • left
  • right
  • top-left
  • top-right
  • bottom-left
  • bottom-right

--margin-top

Set the output canvas top margin.

Syntax:
--margin-top TOP
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Examples:
  • Wide margin for framing: "1in"
  • Minimal margin for web images: "10mm"

--margin-right

Set the output canvas right margin.

Syntax:
--margin-right RIGHT
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Examples:
  • Wide margin for framing: "1in"
  • Minimal margin for web images: "10mm"

--margin-bottom

Set the output canvas bottom margin.

Syntax:
--margin-bottom BOTTOM
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Examples:
  • Wide margin for framing: "1in"
  • Minimal margin for web images: "10mm"

--margin-left

Set the output canvas left margin.

Syntax:
--margin-left LEFT
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Examples:
  • Wide margin for framing: "1in"
  • Minimal margin for web images: "10mm"

--margins

Set the output canvas margins. Create white space around the image for framing, borders, or print bleed.

Syntax:
--margins TOP RIGHT BOTTOM LEFT
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.
Constraint:
  • The value must be specified in inches 'in', millimeters 'mm', centimeters 'cm', pixels 'px', or points 'pt'.

--canvas-background-color

The canvas background color in RGB or RGBA hexadecimal format. The color fills the entire canvas regardless of margins. If no canvas size is specified and the image format supports background (e.g. PDF, PNG), the background color is applied too.

Syntax:
--canvas-background-color COLOR
Constraint:
  • The value must be in RRGGBB or RRGGBBAA hexadecimal format.
Examples:
  • red color: "FF0000"
  • green color: "00ff00"
  • green color with 50% opacity: "00ff0080"

--dpi

Set the DPI resolution of the input image. The DPI affects margin options specified in points too (e.g. 1 point is equal to 1 pixel in 96 DPI).

Syntax:
--dpi DPI
Default:
96
Example:
  • The DPI used for printers. 1 inch contains 300 points: 300

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

--converter-version

Set the converter version. Different versions may produce different output. Choose which one provides the best output for your case.

Syntax:
--converter-version VERSION
Default:
24.04
Allowed Values:
  • 24.04 — Version 24.04.
  • 20.10 — Version 20.10.
  • 18.10 — Version 18.10.

--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