CLI Reference

This document contains the help content for the agx command-line program.

Command Overview:

agx↴
agx apply↴
agx edit↴
agx batch-apply↴
agx batch-edit↴
agx multi-apply↴
agx validate↴

`agx`

Photo editing CLI with portable TOML presets

Usage: agx [OPTIONS] <COMMAND>

Subcommands:

apply — Apply a TOML preset to an image
edit — Edit an image with inline parameters
batch-apply — Apply a TOML preset to all images in a directory
batch-edit — Edit all images in a directory with inline parameters
multi-apply — Apply multiple presets to a single image (decode once, render per preset)
validate — Validate one or more preset files for correctness without rendering

Options:

--gpu — Use GPU acceleration (opt-in). Falls back to CPU if no GPU is available

`agx apply`

Apply a TOML preset to an image

Usage: agx apply [OPTIONS] --input <INPUT> --output <OUTPUT> <--preset <PRESET>|--presets <PRESETS>...>

Options:

-i, --input <INPUT> — Input image path
-p, --preset <PRESET> — Preset TOML file path (single preset, full replacement)
--presets <PRESETS> — Preset TOML files to layer (left-to-right, last-write-wins)
-o, --output <OUTPUT> — Output image path
--quality <QUALITY> — JPEG output quality (1-100, default 92)

Default value: 92
--format <FORMAT> — Output format (jpeg, png, tiff). Inferred from extension if not specified

`agx edit`

Edit an image with inline parameters

Usage: agx edit [OPTIONS] --input <INPUT> --output <OUTPUT>

Options:

-i, --input <INPUT> — Input image path
-o, --output <OUTPUT> — Output image path
--exposure <EXPOSURE> — Exposure in stops (-5.0 to +5.0)

Default value: 0
--contrast <CONTRAST> — Contrast (-100 to +100)

Default value: 0
--highlights <HIGHLIGHTS> — Highlights (-100 to +100)

Default value: 0
--shadows <SHADOWS> — Shadows (-100 to +100)

Default value: 0
--whites <WHITES> — Whites (-100 to +100)

Default value: 0
--blacks <BLACKS> — Blacks (-100 to +100)

Default value: 0
--temperature <TEMPERATURE> — White balance temperature shift

Default value: 0
--tint <TINT> — White balance tint shift

Default value: 0
--lut <LUT> — Path to a .cube LUT file
--vignette-amount <VIGNETTE_AMOUNT> — Vignette amount (-100 to +100). Negative darkens edges, positive brightens

Default value: 0
--vignette-shape <VIGNETTE_SHAPE> — Vignette shape: elliptical (default) or circular

Default value: elliptical
--cg-shadows-hue <CG_SHADOWS_HUE> — Color grading: shadow wheel hue (0-360 degrees)

Default value: 0
--cg-shadows-sat <CG_SHADOWS_SAT> — Color grading: shadow wheel saturation (0-100)

Default value: 0
--cg-shadows-lum <CG_SHADOWS_LUM> — Color grading: shadow wheel luminance (-100 to +100)

Default value: 0
--cg-midtones-hue <CG_MIDTONES_HUE> — Color grading: midtone wheel hue (0-360 degrees)

Default value: 0
--cg-midtones-sat <CG_MIDTONES_SAT> — Color grading: midtone wheel saturation (0-100)

Default value: 0
--cg-midtones-lum <CG_MIDTONES_LUM> — Color grading: midtone wheel luminance (-100 to +100)

Default value: 0
--cg-highlights-hue <CG_HIGHLIGHTS_HUE> — Color grading: highlight wheel hue (0-360 degrees)

Default value: 0
--cg-highlights-sat <CG_HIGHLIGHTS_SAT> — Color grading: highlight wheel saturation (0-100)

Default value: 0
--cg-highlights-lum <CG_HIGHLIGHTS_LUM> — Color grading: highlight wheel luminance (-100 to +100)

Default value: 0
--cg-global-hue <CG_GLOBAL_HUE> — Color grading: global wheel hue (0-360 degrees)

Default value: 0
--cg-global-sat <CG_GLOBAL_SAT> — Color grading: global wheel saturation (0-100)

Default value: 0
--cg-global-lum <CG_GLOBAL_LUM> — Color grading: global wheel luminance (-100 to +100)

Default value: 0
--cg-balance <CG_BALANCE> — Color grading: shadow/highlight balance (-100 to +100)

Default value: 0
--tc-rgb <TC_RGB> — Tone curve — RGB master channel points (e.g. "0.0:0.0,0.25:0.15,0.75:0.85,1.0:1.0")
--tc-luma <TC_LUMA> — Tone curve — Luminance channel points
--tc-red <TC_RED> — Tone curve — Red channel points
--tc-green <TC_GREEN> — Tone curve — Green channel points
--tc-blue <TC_BLUE> — Tone curve — Blue channel points
--sharpen-amount <SHARPEN_AMOUNT> — Sharpening amount (0-100)

Default value: 0
--sharpen-radius <SHARPEN_RADIUS> — Sharpening radius / sigma (0.5-3.0)

Default value: 1
--sharpen-threshold <SHARPEN_THRESHOLD> — Sharpening threshold (0-100). Higher = sharpen finer detail

Default value: 25
--sharpen-masking <SHARPEN_MASKING> — Sharpening masking (0-100). Limits sharpening to textured areas

Default value: 0
--clarity <CLARITY> — Clarity: local contrast at medium frequencies (-100 to +100)

Default value: 0
--texture <TEXTURE> — Texture: local contrast at high frequencies (-100 to +100)

Default value: 0
--dehaze-amount <DEHAZE_AMOUNT> — Dehaze amount (-100 to +100). Positive removes haze, negative adds haze

Default value: 0
--nr-luminance <NR_LUMINANCE> — Noise reduction: luminance strength (0-100)

Default value: 0
--nr-color <NR_COLOR> — Noise reduction: color strength (0-100)

Default value: 0
--nr-detail <NR_DETAIL> — Noise reduction: detail preservation (0-100)

Default value: 0
--grain-type <GRAIN_TYPE> — Grain type (fine, silver, harsh)

Default value: silver
--grain-amount <GRAIN_AMOUNT> — Grain amount (0-100)

Default value: 0
--grain-size <GRAIN_SIZE> — Grain size (0-100)

Default value: 50
--hsl-red-hue <HSL_RED_HUE> (alias: hsl-red-h) — Red hue shift (-180 to +180 degrees)

Default value: 0
--hsl-red-saturation <HSL_RED_SATURATION> (alias: hsl-red-s) — Red saturation (-100 to +100)

Default value: 0
--hsl-red-luminance <HSL_RED_LUMINANCE> (alias: hsl-red-l) — Red luminance (-100 to +100)

Default value: 0
--hsl-orange-hue <HSL_ORANGE_HUE> (alias: hsl-orange-h) — Orange hue shift (-180 to +180 degrees)

Default value: 0
--hsl-orange-saturation <HSL_ORANGE_SATURATION> (alias: hsl-orange-s) — Orange saturation (-100 to +100)

Default value: 0
--hsl-orange-luminance <HSL_ORANGE_LUMINANCE> (alias: hsl-orange-l) — Orange luminance (-100 to +100)

Default value: 0
--hsl-yellow-hue <HSL_YELLOW_HUE> (alias: hsl-yellow-h) — Yellow hue shift (-180 to +180 degrees)

Default value: 0
--hsl-yellow-saturation <HSL_YELLOW_SATURATION> (alias: hsl-yellow-s) — Yellow saturation (-100 to +100)

Default value: 0
--hsl-yellow-luminance <HSL_YELLOW_LUMINANCE> (alias: hsl-yellow-l) — Yellow luminance (-100 to +100)

Default value: 0
--hsl-green-hue <HSL_GREEN_HUE> (alias: hsl-green-h) — Green hue shift (-180 to +180 degrees)

Default value: 0
--hsl-green-saturation <HSL_GREEN_SATURATION> (alias: hsl-green-s) — Green saturation (-100 to +100)

Default value: 0
--hsl-green-luminance <HSL_GREEN_LUMINANCE> (alias: hsl-green-l) — Green luminance (-100 to +100)

Default value: 0
--hsl-aqua-hue <HSL_AQUA_HUE> (alias: hsl-aqua-h) — Aqua hue shift (-180 to +180 degrees)

Default value: 0
--hsl-aqua-saturation <HSL_AQUA_SATURATION> (alias: hsl-aqua-s) — Aqua saturation (-100 to +100)

Default value: 0
--hsl-aqua-luminance <HSL_AQUA_LUMINANCE> (alias: hsl-aqua-l) — Aqua luminance (-100 to +100)

Default value: 0
--hsl-blue-hue <HSL_BLUE_HUE> (alias: hsl-blue-h) — Blue hue shift (-180 to +180 degrees)

Default value: 0
--hsl-blue-saturation <HSL_BLUE_SATURATION> (alias: hsl-blue-s) — Blue saturation (-100 to +100)

Default value: 0
--hsl-blue-luminance <HSL_BLUE_LUMINANCE> (alias: hsl-blue-l) — Blue luminance (-100 to +100)

Default value: 0
--hsl-purple-hue <HSL_PURPLE_HUE> (alias: hsl-purple-h) — Purple hue shift (-180 to +180 degrees)

Default value: 0
--hsl-purple-saturation <HSL_PURPLE_SATURATION> (alias: hsl-purple-s) — Purple saturation (-100 to +100)

Default value: 0
--hsl-purple-luminance <HSL_PURPLE_LUMINANCE> (alias: hsl-purple-l) — Purple luminance (-100 to +100)

Default value: 0
--hsl-magenta-hue <HSL_MAGENTA_HUE> (alias: hsl-magenta-h) — Magenta hue shift (-180 to +180 degrees)

Default value: 0
--hsl-magenta-saturation <HSL_MAGENTA_SATURATION> (alias: hsl-magenta-s) — Magenta saturation (-100 to +100)

Default value: 0
--hsl-magenta-luminance <HSL_MAGENTA_LUMINANCE> (alias: hsl-magenta-l) — Magenta luminance (-100 to +100)

Default value: 0
--quality <QUALITY> — JPEG output quality (1-100, default 92)

Default value: 92
--format <FORMAT> — Output format (jpeg, png, tiff). Inferred from extension if not specified

`agx batch-apply`

Apply a TOML preset to all images in a directory

Usage: agx batch-apply [OPTIONS] --preset <PRESET> --input-dir <INPUT_DIR> --output-dir <OUTPUT_DIR>

Options:

-p, --preset <PRESET> — Preset TOML file path
--input-dir <INPUT_DIR> — Directory containing input images
--output-dir <OUTPUT_DIR> — Directory for output images (created if missing)
-r, --recursive — Recurse into subdirectories

Default value: false
-j, --jobs <JOBS> — Number of parallel workers (0 = auto-detect CPU cores)

Default value: 0
--skip-errors — Continue processing when individual files fail

Default value: false
--suffix <SUFFIX> — Append suffix to output filenames (e.g., _edited)
--quality <QUALITY> — JPEG output quality (1-100, default 92)

Default value: 92
--format <FORMAT> — Output format (jpeg, png, tiff). Inferred from extension if not specified

`agx batch-edit`

Edit all images in a directory with inline parameters

Usage: agx batch-edit [OPTIONS] --input-dir <INPUT_DIR> --output-dir <OUTPUT_DIR>

Options:

--exposure <EXPOSURE> — Exposure in stops (-5.0 to +5.0)

Default value: 0
--contrast <CONTRAST> — Contrast (-100 to +100)

Default value: 0
--highlights <HIGHLIGHTS> — Highlights (-100 to +100)

Default value: 0
--shadows <SHADOWS> — Shadows (-100 to +100)

Default value: 0
--whites <WHITES> — Whites (-100 to +100)

Default value: 0
--blacks <BLACKS> — Blacks (-100 to +100)

Default value: 0
--temperature <TEMPERATURE> — White balance temperature shift

Default value: 0
--tint <TINT> — White balance tint shift

Default value: 0
--lut <LUT> — Path to a .cube LUT file
--vignette-amount <VIGNETTE_AMOUNT> — Vignette amount (-100 to +100). Negative darkens edges, positive brightens

Default value: 0
--vignette-shape <VIGNETTE_SHAPE> — Vignette shape: elliptical (default) or circular

Default value: elliptical
--cg-shadows-hue <CG_SHADOWS_HUE> — Color grading: shadow wheel hue (0-360 degrees)

Default value: 0
--cg-shadows-sat <CG_SHADOWS_SAT> — Color grading: shadow wheel saturation (0-100)

Default value: 0
--cg-shadows-lum <CG_SHADOWS_LUM> — Color grading: shadow wheel luminance (-100 to +100)

Default value: 0
--cg-midtones-hue <CG_MIDTONES_HUE> — Color grading: midtone wheel hue (0-360 degrees)

Default value: 0
--cg-midtones-sat <CG_MIDTONES_SAT> — Color grading: midtone wheel saturation (0-100)

Default value: 0
--cg-midtones-lum <CG_MIDTONES_LUM> — Color grading: midtone wheel luminance (-100 to +100)

Default value: 0
--cg-highlights-hue <CG_HIGHLIGHTS_HUE> — Color grading: highlight wheel hue (0-360 degrees)

Default value: 0
--cg-highlights-sat <CG_HIGHLIGHTS_SAT> — Color grading: highlight wheel saturation (0-100)

Default value: 0
--cg-highlights-lum <CG_HIGHLIGHTS_LUM> — Color grading: highlight wheel luminance (-100 to +100)

Default value: 0
--cg-global-hue <CG_GLOBAL_HUE> — Color grading: global wheel hue (0-360 degrees)

Default value: 0
--cg-global-sat <CG_GLOBAL_SAT> — Color grading: global wheel saturation (0-100)

Default value: 0
--cg-global-lum <CG_GLOBAL_LUM> — Color grading: global wheel luminance (-100 to +100)

Default value: 0
--cg-balance <CG_BALANCE> — Color grading: shadow/highlight balance (-100 to +100)

Default value: 0
--tc-rgb <TC_RGB> — Tone curve — RGB master channel points (e.g. "0.0:0.0,0.25:0.15,0.75:0.85,1.0:1.0")
--tc-luma <TC_LUMA> — Tone curve — Luminance channel points
--tc-red <TC_RED> — Tone curve — Red channel points
--tc-green <TC_GREEN> — Tone curve — Green channel points
--tc-blue <TC_BLUE> — Tone curve — Blue channel points
--sharpen-amount <SHARPEN_AMOUNT> — Sharpening amount (0-100)

Default value: 0
--sharpen-radius <SHARPEN_RADIUS> — Sharpening radius / sigma (0.5-3.0)

Default value: 1
--sharpen-threshold <SHARPEN_THRESHOLD> — Sharpening threshold (0-100). Higher = sharpen finer detail

Default value: 25
--sharpen-masking <SHARPEN_MASKING> — Sharpening masking (0-100). Limits sharpening to textured areas

Default value: 0
--clarity <CLARITY> — Clarity: local contrast at medium frequencies (-100 to +100)

Default value: 0
--texture <TEXTURE> — Texture: local contrast at high frequencies (-100 to +100)

Default value: 0
--dehaze-amount <DEHAZE_AMOUNT> — Dehaze amount (-100 to +100). Positive removes haze, negative adds haze

Default value: 0
--nr-luminance <NR_LUMINANCE> — Noise reduction: luminance strength (0-100)

Default value: 0
--nr-color <NR_COLOR> — Noise reduction: color strength (0-100)

Default value: 0
--nr-detail <NR_DETAIL> — Noise reduction: detail preservation (0-100)

Default value: 0
--grain-type <GRAIN_TYPE> — Grain type (fine, silver, harsh)

Default value: silver
--grain-amount <GRAIN_AMOUNT> — Grain amount (0-100)

Default value: 0
--grain-size <GRAIN_SIZE> — Grain size (0-100)

Default value: 50
--hsl-red-hue <HSL_RED_HUE> (alias: hsl-red-h) — Red hue shift (-180 to +180 degrees)

Default value: 0
--hsl-red-saturation <HSL_RED_SATURATION> (alias: hsl-red-s) — Red saturation (-100 to +100)

Default value: 0
--hsl-red-luminance <HSL_RED_LUMINANCE> (alias: hsl-red-l) — Red luminance (-100 to +100)

Default value: 0
--hsl-orange-hue <HSL_ORANGE_HUE> (alias: hsl-orange-h) — Orange hue shift (-180 to +180 degrees)

Default value: 0
--hsl-orange-saturation <HSL_ORANGE_SATURATION> (alias: hsl-orange-s) — Orange saturation (-100 to +100)

Default value: 0
--hsl-orange-luminance <HSL_ORANGE_LUMINANCE> (alias: hsl-orange-l) — Orange luminance (-100 to +100)

Default value: 0
--hsl-yellow-hue <HSL_YELLOW_HUE> (alias: hsl-yellow-h) — Yellow hue shift (-180 to +180 degrees)

Default value: 0
--hsl-yellow-saturation <HSL_YELLOW_SATURATION> (alias: hsl-yellow-s) — Yellow saturation (-100 to +100)

Default value: 0
--hsl-yellow-luminance <HSL_YELLOW_LUMINANCE> (alias: hsl-yellow-l) — Yellow luminance (-100 to +100)

Default value: 0
--hsl-green-hue <HSL_GREEN_HUE> (alias: hsl-green-h) — Green hue shift (-180 to +180 degrees)

Default value: 0
--hsl-green-saturation <HSL_GREEN_SATURATION> (alias: hsl-green-s) — Green saturation (-100 to +100)

Default value: 0
--hsl-green-luminance <HSL_GREEN_LUMINANCE> (alias: hsl-green-l) — Green luminance (-100 to +100)

Default value: 0
--hsl-aqua-hue <HSL_AQUA_HUE> (alias: hsl-aqua-h) — Aqua hue shift (-180 to +180 degrees)

Default value: 0
--hsl-aqua-saturation <HSL_AQUA_SATURATION> (alias: hsl-aqua-s) — Aqua saturation (-100 to +100)

Default value: 0
--hsl-aqua-luminance <HSL_AQUA_LUMINANCE> (alias: hsl-aqua-l) — Aqua luminance (-100 to +100)

Default value: 0
--hsl-blue-hue <HSL_BLUE_HUE> (alias: hsl-blue-h) — Blue hue shift (-180 to +180 degrees)

Default value: 0
--hsl-blue-saturation <HSL_BLUE_SATURATION> (alias: hsl-blue-s) — Blue saturation (-100 to +100)

Default value: 0
--hsl-blue-luminance <HSL_BLUE_LUMINANCE> (alias: hsl-blue-l) — Blue luminance (-100 to +100)

Default value: 0
--hsl-purple-hue <HSL_PURPLE_HUE> (alias: hsl-purple-h) — Purple hue shift (-180 to +180 degrees)

Default value: 0
--hsl-purple-saturation <HSL_PURPLE_SATURATION> (alias: hsl-purple-s) — Purple saturation (-100 to +100)

Default value: 0
--hsl-purple-luminance <HSL_PURPLE_LUMINANCE> (alias: hsl-purple-l) — Purple luminance (-100 to +100)

Default value: 0
--hsl-magenta-hue <HSL_MAGENTA_HUE> (alias: hsl-magenta-h) — Magenta hue shift (-180 to +180 degrees)

Default value: 0
--hsl-magenta-saturation <HSL_MAGENTA_SATURATION> (alias: hsl-magenta-s) — Magenta saturation (-100 to +100)

Default value: 0
--hsl-magenta-luminance <HSL_MAGENTA_LUMINANCE> (alias: hsl-magenta-l) — Magenta luminance (-100 to +100)

Default value: 0
--input-dir <INPUT_DIR> — Directory containing input images
--output-dir <OUTPUT_DIR> — Directory for output images (created if missing)
-r, --recursive — Recurse into subdirectories

Default value: false
-j, --jobs <JOBS> — Number of parallel workers (0 = auto-detect CPU cores)

Default value: 0
--skip-errors — Continue processing when individual files fail

Default value: false
--suffix <SUFFIX> — Append suffix to output filenames (e.g., _edited)
--quality <QUALITY> — JPEG output quality (1-100, default 92)

Default value: 92
--format <FORMAT> — Output format (jpeg, png, tiff). Inferred from extension if not specified

`agx multi-apply`

Apply multiple presets to a single image (decode once, render per preset)

Usage: agx multi-apply [OPTIONS] --input <INPUT> --preset <PRESET>... --output <OUTPUT>

Options:

-i, --input <INPUT> — Input image path
-p, --preset <PRESET> — Preset TOML file(s) to apply (one output per preset)
-o, --output <OUTPUT> — Output directory (created if missing)
--noop — Also render a no-preset (identity) output

Default value: false
-j, --jobs <JOBS> — Number of preset renders to run concurrently (default: 1)

Default value: 1

`agx validate`

Validate one or more preset files for correctness without rendering.

Reports unknown fields, type mismatches, out-of-range values, missing LUT files, and extends chain problems. Exits 0 if all clean, 1 if any file has errors.

Usage: agx validate [OPTIONS] <PATHS>...

Arguments:

<PATHS> — Paths to preset TOML files. Use shell glob to validate many at once

Options:

-q, --quiet — Suppress "ok" lines for clean files; only show files with errors
--format <FORMAT> — Output format

Default value: human

Possible values:
- human: Human-readable text output (default)
- json: Machine-readable JSON output

AgX