manpages

sail(1)

SAIL(1) SAIL command-line utility SAIL(1)

NAME

sail - SAIL command-line utility for image conversion

SYNOPSIS

sail [OPTIONS] COMMAND [ARGUMENTS]

DESCRIPTION

SAIL (Simple Abstract Imaging Library) is a cross-platform imaging library that provides a unified API for loading, saving, and manipulating images in various formats.

GLOBAL OPTIONS

-h, --help
Display help message and exit.
-v, --version
Display version information and exit.
-l, --log-level LEVEL
Set log level. Valid levels are:
  • silence - No output
  • error - Error messages only
  • warning - Warnings and errors (default)
  • info - Informational messages
  • message - All messages
  • debug - Debug information
  • trace - Detailed trace information

COMMANDS

list

List all supported image codecs with details.

Usage:

sail list [-v]

-v
Verbose output with detailed codec information.

convert

Convert, compose, and extract image files.

Usage:

sail convert [OPTIONS] INPUT... OUTPUT

-p, --pixel-format FORMAT
Force specific output pixel format. Common formats include:
  • BPP24-RGB - 24-bit RGB
  • BPP32-RGBA - 32-bit RGBA
  • BPP8-GRAYSCALE - 8-bit grayscale
  • BPP8-INDEXED - 8-bit indexed color

-c, --compression LEVEL
Set compression quality level (codec-specific). Use -1 for default compression.

-m, --max-frames COUNT
Limit number of frames to process. Use 0 to process all frames.

-n, --frame-number N
Extract specific frame number N (1-based). This is useful for extracting a single frame from animated images.

-d, --delay MS
Set frame delay for animations in milliseconds.

-e, --extract-frames
Extract each frame to separate file. Output filename will be in the format BASE-N.EXT where N is the frame number.
-z, --suffix-digits N
Set number of digits in frame suffix when extracting frames (1-10). For example, with -z 3, frames will be named BASE-001.EXT, BASE-002.EXT, etc.

-C, --colors N
Quantize image to N colors (2-256) using Wu algorithm. This reduces the number of colors in the image for smaller file sizes.

-D, --dither
Apply Floyd-Steinberg dithering for better gradients when reducing colors.

-b, --background COLOR
Blend alpha channel with background color. Valid colors are:
  • white - White background
  • black - Black background
  • #RRGGBB - Hex color code (e.g., #FF0000 for red)

-s, --strip
Remove all metadata from output files.

-H, --flip-horizontal
Flip image horizontally (mirror left-right).

-V, --flip-vertical
Flip image vertically (mirror top-bottom).

probe

Display detailed information about image file without fully decoding it. This command reads only the image header/metadata, making it very fast.

Usage:

sail probe PATH

Note: Due to codec-specific limitations, probe may decode pixels for some codecs, but SAIL makes every effort to avoid full decoding.

decode

Decode file and show information for all frames. Unlike probe, this command fully decodes all frames in the image, which provides more accurate information but takes longer, especially for large or animated images.

Usage:

sail decode PATH

resize

Resize image to specified dimensions.

Usage:

sail resize [OPTIONS] INPUT WxH [OUTPUT]

The dimensions can be specified in several formats:

  • WxH - Fixed width and height (e.g., 800x600)
  • Wx - Fixed width, keep original height (e.g., 800x)
  • xH - Fixed height, keep original width (e.g., x600)
  • Wx0 - Fixed width, calculate height proportionally (e.g., 800x0)
  • 0xH - Fixed height, calculate width proportionally (e.g., 0x800)
  • PERCENT% - Scale both dimensions by percentage (e.g., 50%)
  • W%xH% - Scale width and height by different percentages (e.g., 50%x75%)
  • W%x - Scale width by percentage, keep height (e.g., 25%x)
  • xH% - Scale height by percentage, keep width (e.g., x50%)

-m, --method METHOD
Resizing method. Valid methods are:
  • nearest - Nearest neighbor (fastest, lowest quality)
  • bilinear - Bilinear interpolation (default, good balance)
  • bicubic - Bicubic interpolation (slower, higher quality)
  • lanczos - Lanczos resampling (slowest, highest quality)

-i, --in-place
Overwrite input file safely. When this option is used, the output file argument should be omitted. The operation creates a temporary file and atomically replaces the original file upon success.

-y, --yes
Automatically overwrite existing files without prompting.

EXAMPLES

Basic conversion:

# Convert JPEG to PNG:

sail convert input.jpg output.png

# Convert with custom quality:

sail convert input.png output.jpg -c 90 -p BPP24-RGB

Animation handling:

# Convert animation with specified frame delay:

sail convert animation.gif output.webp -d 100

# Convert animation to multi-page document:

sail convert animation.gif output.tiff

# Compose multiple images into single animation:

sail convert frame1.png frame2.png frame3.png animation.gif -d 100

Frame extraction:

# Extract all frames from animation:

sail convert animation.gif frame.jpg -e

# Extract first 5 frames only:

sail convert animation.webp frame.png -e -m 5

# Extract specific frame (e.g., frame 2):

sail convert animation.gif frame2.png -n 2

# Extract frames with 3-digit suffix (frame-001.jpg, frame-002.jpg, ...):

sail convert animation.gif frame.jpg -e -z 3

Color reduction:

# Reduce colors to 16 with dithering:

sail convert photo.jpg output.gif --colors 16 --dither

Alpha channel handling:

# Convert RGBA to RGB with white background:

sail convert transparent.png opaque.jpg --background white

Metadata and transformations:

# Strip metadata for privacy:

sail convert photo.jpg clean.jpg --strip

# Flip image horizontally and vertically:

sail convert photo.jpg flipped.jpg -H -V

Information display:

# Show detailed image information:

sail probe image.png

# Decode and show all frame information:

sail decode animation.gif

# List all supported codecs:

sail list -v

Image resizing:

# Resize image to specific size:

sail resize input.jpg 800x600 output.jpg

# Resize width only (height unchanged):

sail resize input.jpg 800x output.jpg

# Resize width, calculate height proportionally:

sail resize input.jpg 800x0 output.jpg

# Resize to percentage of original size:

sail resize input.jpg 50% output.jpg

# Resize to different percentages for width and height:

sail resize input.jpg 50%x75% output.jpg

# Resize width to percentage, keep height:

sail resize input.jpg 25%x output.jpg

# Resize with bicubic method:

sail resize input.jpg 1920x1080 output.jpg -m bicubic

# Resize in-place (overwrite original file):

sail resize photo.jpg 800x600 -i

SUPPORTED FORMATS

SAIL supports a wide range of image formats including:

AVIF, BMP, GIF, HEIF, ICO, JPEG, JPEG2000, PNG, TIFF, and other.

Use sail list to see all supported formats and their capabilities.

EXIT STATUS

sail returns 0 on success, or a SAIL error code on failure. Common error codes include:

0
Success
3
SAIL_ERROR_OPEN_FILE - Failed to open file (file not found, permission denied, etc.)
9
SAIL_ERROR_INVALID_ARGUMENT - Invalid command line arguments
51
SAIL_ERROR_INVALID_IMAGE - Invalid or corrupted image file

For a complete list of SAIL error codes, see the SAIL library documentation.

SEE ALSO

For more information about SAIL, visit: https://sail.software

AUTHOR

SAIL was written by Dzmitry Baryshau and contributors.

COPYRIGHT

Copyright (c) 2020-2025 Dzmitry Baryshau. Licensed under the MIT License.

October 2025 SAIL 0.9.10