imglife cleanup

Synopsis

imglife cleanup [flags]

Applies the retention policy to all images in build.images and their corresponding mirrors. Deletes (or archives) tags that exceed keep_last or max_age_days.

Flags

Flag	Default	Description
--dry-run	false	Simulate deletions without making any changes
--list	false	Print affected tags and exit
--force	false	Override the safety guard and clean up even when no applicative-referenced base images are found

Examples

# Preview: show what would be deleted
imglife cleanup --list

# Dry-run: simulate without deleting
imglife cleanup --dry-run

# Apply the retention policy
imglife cleanup

Deletion criteria

A tag is a deletion candidate if it satisfies either condition:

1. Its position in the sorted tag list exceeds keep_last.
2. Its creation timestamp is older than max_age_days days.

Tags listed in retention.exclude_tags are never deleted.

Safety guard

A base image tag is also protected when it is referenced by an applicative build record stored in the package registry. To avoid mass deletion, when build.images are configured but applicative build records exist that yield no referenced base image — or some records cannot be read — cleanup aborts instead of treating every base image as unreferenced.

The guard does not engage when the package registry cleanly reports no applicative build records at all: that is a young project whose applicative pipelines have not published anything yet, with nothing that could be mistaken for unreferenced. Cleanup then proceeds under the normal keep_last / max_age_days policies. A misconfigured or unreachable registry surfaces earlier as an explicit error rather than an empty list.

Pass --force to override the guard, for example once all applicative records have genuinely been removed. The guard never engages for mirror-only setups (no build.images) or in --dry-run/--list mode.

Archive mode

When retention.archive.enabled: true, tags are copied to retention.archive.registry before deletion. This creates a safety net for accidentally deleted images.

After retention.archive.keep_days days, the archived copy is deleted on the next cleanup run.

Orphan detection

imglife reports images that exist in the OCI registry but are no longer declared in build.images. These “type-orphan” images appear in the --list output with a warning but are not automatically deleted. Remove them manually after verification.

Configuration

retention:
  keep_last: 5
  max_age_days: 90
  exclude_tags: [latest, stable]
  archive:
    enabled: true
    registry: registry.example.com/archive
    keep_days: 180

See retention configuration for the full reference.

Summary report

After each run (not in --list mode), imglife prints a summary to stdout:

  Cleanup Summary · 3.8s
  ───────────────────────────────────
  Tags examined           24
  ├─ Deleted              5
  ├─ Archived             2
  ├─ Kept                 17
  └─ Errors               0

In --dry-run mode the header is prefixed with [dry-run]. Set NO_COLOR=1 or TERM=dumb to disable ANSI colors.

Exit codes

Code	Meaning
0	Cleanup completed (including partial deletions)
1	Fatal error preventing cleanup