Caesium Command Line Tools

caesiumclt is a powerful command-line tool for image compression written in Rust that delivers exceptional results with minimal effort. Whether you need pixel-perfect lossless compression or aggressive size reduction, caesiumclt has you covered.

Built on the robust libcaesium engine, it combines high performance with flexibility to fit seamlessly into your workflow.

✨ Features

• Multiple Compression Modes

  • 🔍 Quality-based lossy compression
  • 💎 Lossless compression—preserve image quality while reducing size
  • 📏 Maximum size compression - target specific file sizes

• Advanced Image Processing

  • 📐 Resize images with multiple options (width, height, long/short edge)
  • 🔄 Convert between formats (JPEG, PNG, WebP)
  • 🏷️ EXIF metadata preservation

• Workflow Optimization

  • *️⃣ Recursive directory compression
  • 📁 Folder structure preservation
  • 🕒 File timestamp preservation
  • 📝 Custom suffix for output files
  • ⚡ Fast and customizable multithreaded processing

Supported Formats

Format	Lossy	Lossless
JPEG	✅	✅
PNG	✅	✅
WebP	✅	✅
GIF	✅	❌

🚀 Getting Started

Binaries

Download the latest binaries from the release page.

Supported platforms:

• Windows (x86_64)
• macOS (x86_64/aarch64)
• Linux (x86_64/aarch64)

Installation

Cargo

cargo install caesiumclt

Homebrew

brew install caesiumclt

🛠️ Development

Requirements

• Rust >= 1.79.0

Quick Start

1. Clone the repository:

   git clone https://github.com/Lymphatus/caesium-clt.git
   cd caesium-clt

2. Build the project:

   cargo build

3. Build for release (optimized):

   cargo build --release

4. Run the tool directly:

   cargo run -- [your-arguments-here]

5. Run tests:

   cargo test

📖 Usage

For a complete list of all flags and options, refer to the full documentation.

Examples

Lossless compression:

# Compress a single image
$ caesiumclt --lossless -o output/ image.jpg

# Compress with metadata preservation
$ caesiumclt --lossless -e --keep-dates -o output/ image.jpg

# Compress a directory recursively
$ caesiumclt --lossless -R -o output/ Pictures

# Preserve folder structure
$ caesiumclt --lossless -RS -o output/ Pictures

Lossy compression:

# Compress with quality setting
$ caesiumclt -q 80 -o output/ image.jpg

# Compress multiple images with a specific quality
$ caesiumclt -q 75 -o output/ image1.jpg image2.png image3.webp

# Compress with suffix to avoid overwriting originals
$ caesiumclt -q 85 --suffix _compressed --same-folder-as-input image.jpg

Format conversion:

# Convert images to WebP format with quality setting
$ caesiumclt -q 85 --format webp -o output/ Pictures/*.jpg

# Convert PNG to JPEG with maximum quality
$ caesiumclt -q 100 --format jpeg -o output/ image.png

Resizing options:

# Resize to specific width (maintaining aspect ratio)
$ caesiumclt --lossless --width 1920 -o output/ image.jpg

# Resize to specific height (maintaining aspect ratio)
$ caesiumclt -q 90 --height 1080 -o output/ image.jpg

# Resize by longest edge (useful for mixed portrait/landscape photos)
$ caesiumclt -q 85 --long-edge 1500 -o output/ Pictures/*.jpg

# Resize by shortest edge
$ caesiumclt -q 85 --short-edge 800 -o output/ Pictures/*.jpg

Advanced options:

# Target a specific maximum file size (500KB)
$ caesiumclt --max-size 512000 -o output/ large-image.jpg

# Parallel processing with specific thread count
$ caesiumclt -q 80 --threads 4 -R -o output/ Pictures/

# Dry run to test compression without writing files
$ caesiumclt -q 80 --dry-run -o output/ Pictures/

# PNG optimization with highest compression level
$ caesiumclt --lossless --png-opt-level 6 -o output/ image.png

# JPEG advanced options with specific chroma subsampling
$ caesiumclt -q 85 --jpeg-chroma-subsampling "4:2:0" --jpeg-baseline -o output/ image.jpg

Overwrite policies:

# Never overwrite existing files
$ caesiumclt -q 85 -O never -o output/ Pictures/*.jpg

# Overwrite only if the existing file is bigger
$ caesiumclt -q 85 -O bigger -o output/ Pictures/*.jpg