bnema.dev

Images Command

List and prune runtime/registry images.

gordon images

gordon images <subcommand>

Subcommands:

  • list - List runtime images and registry tags.
  • prune - Prune dangling runtime images and old registry tags.
  • tags - List registry tags for a specific repository.

Note: Images commands require remote mode (--remote + --token, or configured remotes).

gordon images list

gordon images list
gordon images list --json

Shows image rows with repository, tag, size, creation time, image id, and dangling status. Rows that exist only in the registry (not currently present in the runtime cache) are included with unavailable runtime fields shown as -.

Flags:

Flag Description
--json Output images as JSON

JSON Output

gordon images list --json

[
  {
    "repository": "myapp",
    "tag": "latest",
    "size": "148MB",
    "created_at": "2026-03-13T10:15:00Z",
    "image_id": "sha256:abc123def456",
    "dangling": false
  }
]

gordon images prune

gordon images prune [--dry-run] [--keep-releases <n>] [--dangling] [--registry] [--no-confirm]

By default, prune removes dangling runtime images and applies registry tag retention (keeping latest + 3 previous non-latest tags per repository). A confirmation prompt is shown before destructive operations.

Flags:

Flag Default Description
--dry-run false Show prune behavior without applying changes
--keep-releases 3 Number of previous non-latest tags to keep per repository (latest is always preserved)
--dangling false Restrict scope to dangling runtime images only
--registry false Restrict scope to registry tag retention only
--no-confirm false Skip the confirmation prompt

Scope resolution

  • No scope flags (default): both runtime and registry cleanup run.
  • --dangling: only runtime dangling images are pruned; registry is skipped.
  • --registry: only registry tag retention runs; runtime is skipped.
  • --dangling --registry: both scopes run (same as default, but explicit).

Retention semantics

  • latest is always preserved when present.
  • --keep-releases counts non-latest tags, ordered by most recent first.
  • --keep-releases=0 with registry scope enabled still runs registry cleanup but keeps no non-latest tags.

gordon images tags

gordon images tags <repository>
gordon images tags <repository> --json

Lists all tags in the Gordon registry for the specified repository.

Flags:

Flag Description
--json Output repository and tags as JSON

JSON Output

gordon images tags myapp --json

{
  "repository": "myapp",
  "tags": ["latest", "v1.2.0", "v1.1.0"]
}

Examples

# List images
gordon images list

# Prune everything with defaults (dangling + registry, keep latest + 3)
gordon images prune

# List tags for a repository
gordon images tags myapp

# Prune dangling runtime images only
gordon images prune --dangling

# Prune registry tags only, keeping latest + 5 previous
gordon images prune --registry --keep-releases 5

# Preview cleanup without applying
gordon images prune --dry-run

# Skip confirmation prompt
gordon images prune --no-confirm

Required Permissions

  • The list subcommand requires admin:status:read.
  • The prune subcommand requires admin:config:write.
  • The tags subcommand requires admin:status:read.