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

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.

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