How to Set Image Quality with ImageKit CLI: Command Reference and Examples

The ImageKit CLI provides a --quality flag that accepts integer values from 1 to 100 to control JPEG compression levels and PNG compression strategies, defaulting to 85 for optimal file size and visual fidelity.

The hzbd/imagekit repository offers a Rust-based command-line tool for batch image processing. When you need to set image quality with ImageKit CLI, the tool exposes a straightforward --quality parameter that directly influences encoder settings across multiple formats.

Where the --quality Flag Is Defined

In src/cli.rs, the quality parameter is defined as a required unsigned 8-bit integer constrained to the range 1–100, with a default value of 85 (see lines 36-38). This strict type enforcement ensures that only valid quality levels reach the processing pipeline.

When the CLI executes, the parsed quality value flows into the process_image function in src/processor.rs. From there, the save_image_with_format helper routes the value to format-specific encoders based on the output file type.

How Quality Values Map to Image Formats

The --quality flag behaves differently depending on the target image format. The implementation in src/processor.rs (lines 101-121) handles these variations through distinct encoding paths.

JPEG Quality Control

For JPEG images, the CLI passes the exact quality value to JpegEncoder::new_with_quality. This creates a direct correlation between the CLI argument and the JPEG compression level: higher values preserve visual fidelity at the cost of file size, while lower values increase compression artifacts but reduce storage requirements.

PNG Compression Strategy

For PNG images, the quality value maps to a CompressionType rather than a lossy quality setting. According to the source in src/processor.rs (lines 115-121):

• 100 triggers CompressionType::Best (maximum compression, smallest file)
• 1–50 triggers CompressionType::Fast (minimal compression, fastest encoding)
• 51–99 triggers CompressionType::Default (balanced approach)

Other Format Behavior

All other image formats fall back to the default encoder, which ignores the --quality flag. These formats either rely on lossless compression internally or do not expose quality parameters through their encoding APIs.

Command Examples for Setting Image Quality

The following commands demonstrate practical usage of the --quality flag with the ImageKit CLI:

# Process with default quality (85)

imagekit -i ./photos -o ./out

# High-quality JPEG output (90)

imagekit -i ./photos -o ./out --quality 90

# Low-quality JPEG for thumbnails (30)

imagekit -i ./photos -o ./out --quality 30

# Maximum PNG compression (100)

imagekit -i ./photos -o ./out --quality 100

# Combined with resize and watermark operations

imagekit -i ./photos -o ./out \
  --width 800 --height 600 \
  --watermark-text "© MySite" \
  --quality 75

The --quality parameter remains optional; omitting it applies the default value of 85 to compatible formats.

Summary

• The --quality flag is defined in src/cli.rs as an unsigned 8-bit integer ranging from 1 to 100, defaulting to 85.
• JPEG encoding uses the value directly via JpegEncoder::new_with_quality for precise compression control.
• PNG encoding maps the value to CompressionType variants (Best, Fast, or Default) based on the numeric range.
• Other formats ignore the quality setting and use default encoder configurations.
• The parameter integrates seamlessly with other CLI options like --width, --height, and watermarking flags.

Frequently Asked Questions

What is the default image quality in ImageKit CLI?

The default quality value is 85, as defined in src/cli.rs. This value applies automatically when the --quality flag is omitted from the command line, providing a balanced trade-off between visual fidelity and file size for JPEG outputs.

Does the --quality flag affect PNG files?

Yes, but indirectly. For PNG images, the quality value determines the CompressionType rather than a lossy quality level. A value of 100 enables Best compression (smallest file size), values 1–50 select Fast compression (quicker encoding), and values 51–99 use Default compression as implemented in src/processor.rs.

What happens if I specify a quality value outside the 1–100 range?

The CLI enforces the range at the argument parsing level in src/cli.rs. Since the quality field is defined as a constrained unsigned 8-bit integer, the application rejects invalid inputs before processing begins, ensuring only values between 1 and 100 reach the encoder logic.

Which source files handle quality processing in the ImageKit repository?

Quality handling spans two primary files: src/cli.rs defines the command-line interface and default values, while src/processor.rs contains the process_image and save_image_with_format functions that route quality parameters to the appropriate encoders for JPEG and PNG formats.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}