Using the CLI

This reference covers all available options, batch processing patterns, and preset usage for the pfccmd and pfcaiserver command-line applications.

About the AI server

The AI server (pfcaiserver) is an optional component that can improve performance when processing large batches of images with AI tools. By keeping AI models loaded in memory, it reduces the overhead of loading models for each image processed by pfccmd.

When using the AI server, pfccmd sends image data to the server for scene detection and other AI inference tasks, and the server returns the detected information to pfccmd. This allows pfccmd to focus on image correction while leveraging the server's optimized AI processing. Both CLIs can run on the same machine or on separate machines within a network. The long-running pfcaiserver loads the various AI models once and serves multiple requests from pfccmd clients.

To use it, just run pfcaiserver on the same instance or local network as pfccmd and have pfccmd connect to it as shown below.

Command syntax

The basic syntax for pfccmd is:

pfccmd [options] [paths]

Where [paths] is one or more files or directories to process. When processing multiple files or a directory, output filenames are based on input filenames with a _perfectlyclear suffix added.

Options reference

The following tables list all available command-line options, organized by category.

General options

These options control basic input/output behavior and help.

Stdio options

These options enable reading from standard input and writing to standard output, useful for piping images through other commands.

Resize options

These options control output image dimensions.

When multiple resize parameters are provided, only one is used based on priority order: width → height → long → short → scale.

Processing options

These options control how images are analyzed and corrected.

Red eye correction modes

Scene detection options

These options control AI Scene Detection behavior.

Auto crop options

These options configure automatic face-based cropping for portrait photography. Workbench will export the exact command line arguments and their values from its [Auto Crop tool] (/docs/general-info/presets).

Batch file option

Process a list of images with per-image preset assignments.

The list file format is one image per line, with the image path followed by a space and the preset path:

/images/img_1234.jpg /presets/corrections.preset
/images/img_1235.png /presets/other.preset
"/path/with spaces/image.jpg" "/presets/my preset.preset"

Images in the list file are overwritten with the corrected output.

SDK license protection

For protected SDK builds, you must provide the path to your sdk_license folder. This folder contains your unique license key identifier and is validated online every 12 to 24 hours.

Set the license path using either method:

# Using command-line option
pfccmd -s /path/to/sdk_license input.jpg -o output.jpg

# Using environment variable
export PFC_SDK_LICENSE=/path/to/sdk_license
pfccmd input.jpg -o output.jpg

If both are set, then the -s command-line option takes priority.

Batch examples

The CLI supports several batch processing patterns for high-volume workflows.

Process a directory

Process all supported images in a directory:

pfccmd ./input -o ./output

Output files are named based on input files with _perfectlyclear appended before the extension.

Process with custom preset

Apply a specific preset to all images:

pfccmd ./input -o ./output -p /path/to/corrections.preset

Process with resize

Correct and resize all images to 1000 pixels on the long edge:

pfccmd ./input -o ./output -m long -v 1000

Process with quality setting

Set JPEG output quality to 85:

pfccmd ./input -o ./output -q 85

Skip previously edited images

Skip images that were already processed in Photoshop or Lightroom:

pfccmd ./input -o ./output --skip-exif-software "photoshop,lightroom"

The software names are matched case-insensitively against the EXIF Software (0x0131) and Processing Software (0x000b) tags.

Process using list file

For complex workflows where different images need different presets, use a list file:

pfccmd --image-list-file /path/to/jobs.txt

Where jobs.txt contains:

/photos/portrait1.jpg /presets/portrait.preset
/photos/landscape1.jpg /presets/landscape.preset
/photos/product1.jpg /presets/product.preset

Using presets

Presets define the correction parameters applied to images. You can use the built-in AI Scene Detection or apply custom presets exported from Perfectly Clear Workbench.

AI scene detection

By default, pfccmd uses AI Scene Detection to automatically select optimal corrections based on image content. This is equivalent to:

pfccmd input.jpg -p scene

Or:

pfccmd input.jpg -p auto

Custom presets

To use your own correction settings, export these from Perfectly Clear Workbench.

pfccmd input.jpg -o output.jpg -p /path/to/my_corrections.preset

AI presets with scene detection

You can also export an AI Presets group from Workbench that contains custom presets for each scene type. When you pass this file to pfccmd, Scene Detection is enabled and your custom presets are applied based on detected scene:

pfccmd input.jpg -o output.jpg -p /path/to/AI_Presets.preset

No corrections

To resize or convert an image without applying any corrections:

pfccmd input.jpg -o output.jpg -p none -m long -v 1200

Converting formats

The CLI supports format conversion between JPEG, PNG, and WebP.

Convert by output extension

The simplest method is to specify a different extension in the output filename:

# PNG to JPEG
pfccmd input.png -o output.jpg

# JPEG to PNG
pfccmd input.jpg -o output.png

Convert using output-type flag

When processing directories or using stdio mode, use the --output-type flag:

pfccmd --output-type jpg input.png

This creates input_perfectlyclear.jpg regardless of the input format.

Set output quality

For lossy formats (JPEG, WebP), control quality with -q:

pfccmd input.png -o output.jpg -q 95

Quality ranges from 40 (smallest file, lowest quality) to 100 (largest file, highest quality). The default is 90.

Convert color space

By default, the CLI preserves the original color profile of the input image. You can override this with the --output-color-space option, which is useful to convert all images you process to a specific color space.

Convert output to sRGB:

pfccmd input.jpg -o output.jpg --output-color-space sRGB

Convert to a custom ICC profile:

pfccmd input.jpg -o output.jpg --output-color-space /path/to/profile.icc

Keep the original color profile (default behavior):

pfccmd input.jpg -o output.jpg --output-color-space original

Stdio mode

For integration with pipelines, read from stdin and write to stdout:

pfccmd --stdio < input.jpg > output.jpg

Specify input and output formats explicitly:

pfccmd --stdio --input-type png --output-type jpg < input.png > output.jpg

Environment variables

These environment variables configure pfccmd behavior without command-line options.

Status and exit codes

The CLI returns exit codes to indicate success or failure, useful for scripting and automation.

Job-level exit codes

Understand what each exit code means:

Per-image status messages

When using --json, each image includes a status field:

JSON output

The --json flag outputs detailed information about each processed image. This example shows the structure:

{
  "images": [
    {
      "input": "/path/to/input.jpg",
      "output": "/path/to/output.jpg",
      "status": "ok",
      "message": "",
      "width": 2380,
      "height": 3597,
      "format": 1,
      "scene": 5,
      "noise": "unknown",
      "facesCount": 1,
      "faces": [
        {
          "left": 604,
          "top": 302,
          "width": 384,
          "height": 384,
          "confidence": 100,
          "angle": 1,
          "smile": 26,
          "blink": 0
        }
      ]
    }
  ],
  "status": "ok",
  "message": ""
}

The scene value indicates the detected scene category. Use --list-local-scenes to see available scene labels and their numeric IDs.

Optimize for speed with AI server

For workflows that process many individual images, the AI server (pfcaiserver) improves performance by keeping AI models loaded in memory. This can save up to 30% of processing time per image when using AI Scene Detection and other AI tools.

Start the server

Run pfcaiserver on the same machine or local network as pfccmd:

pfcaiserver

By default, it listens on 127.0.0.1:29170 using TCP.

Configure the server

Example with HTTP on port 8080:

pfcaiserver --http --address 129.168.1.123:8080

Connect pfccmd to the server

Tell pfccmd to use the running server:

pfccmd --scene-detection-server tcp://127.0.0.1:29170 input.jpg -o output.jpg

Or set the environment variable:

export PFC_SD_SERVER=tcp://127.0.0.1:29170
pfccmd input.jpg -o output.jpg

For HTTP connections on a remote server:

pfccmd --scene-detection-server http://129.168.1.123:8080 input.jpg -o output.jpg