Cheat sheet — full reference below.
| Task | Command |
|---|---|
| Is everything wired up? | php eecli.php super_images:doctor |
| What config is active? | php eecli.php super_images:status |
| Preview transforms for one asset | php eecli.php super_images:generate --file=123 --dry-run |
| Generate one asset now | php eecli.php super_images:generate --file=123 |
| Queue a whole volume | php eecli.php super_images:generate --upload-dir=images --queue |
| After switching storage / stale URLs | php eecli.php super_images:cleanup --all --dry-run then regenerate |
Run all commands from the ExpressionEngine system directory (eecli.php).
Every generation path uses the same GenerationService as template tags and the Control Panel.
php eecli.php super_images:status
php eecli.php super_images:status --json| Key | Meaning |
|---|---|
| enabled | Master switch |
| driver | Selected driver after auto fallback |
| driverPreference | Config value (auto, libvips, …) |
| storage | Default adapter handle |
| defaultProfile / defaultFormat | Tag/CLI defaults |
| profileCount | Number of configured profiles |
| queue | Whether BoldMinded Queue bridge is available |
| generateBeforePageLoad | Delivery mode |
Use this first when something looks off — it shows which driver was actually selected (auto can silently fall back to GD if Imagick/libvips are missing).
# Dump the fully-resolved add-on configuration.
php eecli.php super_images:config
# Also include a manifest sample for one File Manager file.
php eecli.php super_images:config --file=123
# Machine-readable output
php eecli.php super_images:config --file=123 --json| Option | Alias | Meaning |
|---|---|---|
| --file | -f | When set, includes a manifest array of planned units (profile, variant, format, identity, storage path, public URL). Shows up to 8 rows in human output. |
| --json | -j | Emit JSON instead of plain text. |
Use this to sanity-check what a specific file would generate before running generate, or to confirm a config change took effect.
Eagerly generates derivatives (profile × variant × format units) for one file or every image in an upload directory, inline or via the queue bridge.
# Preview exactly what would be generated for one file, without writing anything.
php eecli.php super_images:generate --file=123 --dry-run
# Generate every unit for one file right now (inline, in this process).
php eecli.php super_images:generate --file=123
# Generate only the "md" variant / "webp" format for one file.
php eecli.php super_images:generate --file=123 --variant=md --format=webp
# Regenerate even if the derivative already exists (e.g. after encoder/policy change).
php eecli.php super_images:generate --file=123 --force
# Generate every image file in an upload directory (by short name), capped at 50.
php eecli.php super_images:generate --upload-dir=images --limit=50
# Queue generation for the whole directory (recommended for large batches).
php eecli.php super_images:generate --upload-dir=images --queue
# Combine filters and force regeneration.
php eecli.php super_images:generate --upload-dir=images --profile=responsive --variant=lg --format=avif --force| Option | Alias | Default | Meaning |
|---|---|---|---|
| --file | -f | (none) | Generate for a single File Manager file ID. |
| --upload-dir | -u | (none) | Generate for every image (mime_type like image/%) in this upload directory short name. At least one of --file or --upload-dir is required. |
| --profile | -p | (none) | Restrict to one profile handle from config profiles. |
| --variant | -v | (none) | Restrict to one variant handle within the selected profile(s). |
| --format | - | (none) | Restrict to one output format (jpg, webp, avif, …). |
| --dry-run | -d | false | Plan and print units without generating or touching storage. Ignores --queue. |
| --queue | -q | false | Push one queue job per file when BoldMinded Queue is installed. Without the queue add-on, generation stays inline. |
| --force | - | false | Regenerate and overwrite even when a derivative already exists. |
| --limit | -l | 0 | Cap the number of matching files processed (0 = no limit). Applied before unit expansion. |
Generating across 87 files…
[file 1/87] #101 hero.png (6 units)
[1] [generated] responsive/sm.webp → https://yoursite.test/transforms/super-images/…/hero-sm.webp
[2] [already exists] responsive/sm.jpg → https://yoursite.test/transforms/super-images/…/hero-sm.jpg
[3] [failed] responsive/lg.webp — Source file is missing
Summary: generated=430 already_exists=88 failed=2 queued=0 units=520 (41.3s)
Failures:
• #101 hero.png — responsive/lg.webp — Source file is missing[already exists] means the derivative is already in storage and --force was not set.
With --queue, each file is queued as a single job (GenerateFileJob) rather than printing per-unit progress in this process.
# Human-readable PASS/WARN/FAIL report with fix hints.
php eecli.php super_images:doctor
# Same checks, machine-readable JSON.
php eecli.php super_images:doctor --json| Option | Alias | Meaning |
|---|---|---|
| --json | -j | Emit JSON instead of formatted lines. |
Checks cover: PHP version, add-on enabled, GD / Imagick / Libvips availability, selected driver formats, optimizer binaries, storage/markers/temp writability, runtime signing when lazy delivery is enabled, queue bridge, and local/remote sources allow-lists.
Missing optional optimizer binaries report WARN, not PASS. See Diagnostics for health badge rules.
Deletes derivative files under the default storage adapter. For local storage, files are found by scanning the adapter root. For remote adapters (S3, Spaces, R2), cleanup walks the per-file index at {cache_path}super_images/file-index/ and deletes each indexed object — buckets are not listed directly unless cleanup.allowRemoteScan is enabled.
With --all, cleanup also wipes existence markers and the file index so the next generate pass treats every transform as missing (useful after switching storage backends).
Runs for real by default. Pass --dry-run to preview without deleting.
| Mode | How | Retention |
|---|---|---|
| Aged (default) | No mode flag | cleanup.generatedRetentionDays (default 365), overridable with --retention-days |
| All | --all | None — deletes everything immediately |
| File | --file=ID | N/A — deletes that file’s indexed derivatives |
| Orphaned | --orphaned | Same as aged, via index |
| Previews | --previews | cleanup.previewRetentionDays (default 2) |
# Delete aged transforms (older than generatedRetentionDays).
php eecli.php super_images:cleanup --dry-run
# Temporary retention for this run only (e.g. older than 7 days).
php eecli.php super_images:cleanup --retention-days=7 --dry-run
# Nuclear: delete every derivative now, ignore retention, clear index + markers.
php eecli.php super_images:cleanup --all --dry-run
php eecli.php super_images:cleanup --all
# One file’s indexed derivatives.
php eecli.php super_images:cleanup --file=123 --dry-run
# Indexed derivatives whose EE file no longer exists.
php eecli.php super_images:cleanup --orphaned --dry-run
# Playground preview artifacts older than previewRetentionDays.
php eecli.php super_images:cleanup --previews --dry-run| Option | Alias | Default | Meaning |
|---|---|---|---|
| --dry-run | -d | false | List matches without deleting. |
| --file | -f | (none) | Purge all indexed derivatives for one file ID. |
| --orphaned | - | false | Purge derivatives for indexed files that no longer exist in EE. Subject to retention. |
| --previews | - | false | Remove aged Playground files under the preview/ namespace. |
| --all | - | false | Delete every derivative immediately (no retention check). Clears markers and file index when not a dry run. |
| --retention-days | - | (config default) | Temporary override of generatedRetentionDays / previewRetentionDays for aged / orphaned / preview modes. Ignored when --all is set. |
Mode precedence: --file › --previews › --orphaned › --all › aged (default).
Cleaning aged transforms (retention: 365 days)…
[1/18] [deleted] 417627…/101/hero-sm.webp
[2/18] [deleted] 417627…/101/hero-md.webp
Summary: deleted=18 kept=412 failed=0 markers=42 indexes=3 (1.2s)Generated derivatives are meant to be cached for the long haul — regenerating on every deploy defeats the purpose of eager generation. Two independent knobs control preview vs production sweeps:
'cleanup' => [
'previewRetentionDays' => 2,
'generatedRetentionDays' => 365,
'allowRemoteScan' => false,
],generatedRetentionDays does not block the immediate cleanup that runs when a File Manager file is deleted or replaced (see Policies). It only guards the default aged and --orphaned console sweeps. --all bypasses it.
'autoGenerate' => [
'enabled' => true,
'onUpload' => true,
'onReplace' => true,
'queue' => true,
],'upload_directories' => [
'images' => [
'autoGenerate' => true,
'profile' => 'responsive',
],
],When queue is true and BoldMinded Queue is installed, upload/replace triggers GenerateFileJob per file. Without the queue add-on, generation runs inline during the save request.
The same bridge powers optimizers.optimizeType => 'job': same-format post-optimizers (jpegoptim, optipng, …) overwrite the stored file after the response returns. Without Queue, Super Images falls back to inline optimize. Format converters (cwebp, avifenc) always run during generate. See Encoders & optimizers..
Run the queue worker in production (BoldMinded Queue documentation).
*/15 * * * * php /path/to/system/eecli.php super_images:generate --upload-dir=images --queue