CLI Core Commands & Flags

v0.2.1-beta

Comprehensive list of command-line flags, options, aspect ratios, and formatting controls.

The imagerry CLI formats, styles, and compresses images locally from your terminal.

Basic Syntax

|bash

# Single image
imagerry -i <input-file> -o <output-file> [options]

# Unix Streaming (stdin / stdout)
cat input.png | imagerry -i - -o - [options] > output.webp

# Batch directory or glob
imagerry -i <input-dir> -o <output-dir> [options]
imagerry --batch "<glob>" -o <output-dir> [options]

Core Options

Option	Type	Default	Description
`-i, --input <path>`	`string`	—	Path to input file, directory, or `-` for standard input (`stdin`)
`-o, --output <path>`	`string`	—	Path to output file, directory, or `-` for standard output (`stdout`)
`-f, --format <format>`	`string`	auto	Target format: `png`, `jpeg`, or `webp`
`-q, --quality <num>`	`number`	`90`	Quality (1-100) for WebP and JPEG
`-p, --preset <name>`	`string`	`"default"`	Preset name (`mesh`, `gradient`, `cyberpunk`, etc.)
`-b, --batch <glob>`	`string`	—	Batch process multiple files matching a glob pattern
`-c, --concurrency <n>`	`number`	`4`	Parallel workers for batch processing
`--padding <num>`	`number`	—	Direct canvas padding override
`--radius <num>`	`number`	—	Direct inner border radius override
`--shadow <num>`	`number`	—	Direct drop shadow size override
`--bg-color <hex>`	`string`	—	Solid background hex color
`--ratio <ratio>`	`string`	—	Aspect ratio (`16:9`, `1:1`, `4:3`, `auto`)
`--watermark <text>`	`string`	—	Watermark overlay text
`--title <text>`	`string`	—	Header title text overlay
`--subtitle <text>`	`string`	—	Subtitle text overlay
`--license-key <key>`	`string`	`env`	Imagerry Pro license key override
`--no-update-check`	`boolean`	`false`	Disable automatic update check (recommended for CI/CD)
`-v, --version`	`boolean`	—	Print CLI engine version (currently `v0.2.1-beta`)
`-h, --help`	`boolean`	—	Show all commands and options

👉

Official JSON Schema: https://imagerry.com/schema/config.json

Unix Pipelines (Stdin / Stdout)

Imagerry CLI functions as a first-class Unix filter tool. Stream images directly into shell pipelines without writing intermediate files to disk:

|bash

# Read from standard input (stdin)
cat raw-screenshot.png | imagerry -i - -o styled.png --preset mesh

# Stream raw binary output to standard output (stdout)
imagerry -i photo.png -o - --format webp --preset gradient > result.webp

# Full bidirectional pipeline (stdin → stdout)
curl -sL https://example.com/badge.png | imagerry -i - -o - --format webp > optimized.webp

Pro Tip

Clean Stream Guarantee: When streaming binary image data to stdout (-o -), all progress spinners and logs are automatically redirected to stderr or silenced. Your redirected stdout contains 100% clean binary image data.

Standardized POSIX Exit Codes

For reliable shell automation and CI/CD pipelines, Imagerry CLI adheres to standardized exit codes:

Code	Status	Description
`0`	`SUCCESS`	Command completed successfully.
`1`	`GENERAL_ERROR`	Runtime rendering error, filesystem permission error, or server crash.
`2`	`INVALID_ARGUMENT`	Missing required flags, missing input file, or invalid preset/format syntax.
`3`	`LICENSE_ERROR`	License key invalid, expired, burst loop detected, or free tier daily quota exceeded.
`4`	`CRITICAL_UPDATE_REQUIRED`	Obsolete CLI version below the minimum supported version.

Quick Examples

1. Convert & Style to WebP

|bash

imagerry -i hero.png -o hero.webp -q 85 --preset mesh

2. Direct Style Overrides

|bash

imagerry -i app.png -o app.png --preset gradient --padding 48 --radius 20

3. Batch Process a Folder

|bash

imagerry -i ./screenshots -o ./dist --preset cyberpunk --format webp

4. Stream via Pipe

|bash

cat photo.png | imagerry -i - -o - --format webp > styled.webp

5. Initialize Project Config

|bash

imagerry init --preset mesh

Found an issue or typo? Report on GitHub

Imagerry CLI Docs • v0.2.1-beta