1# Images Command
2
3List and prune runtime/registry images.
4
5## gordon images
6
7```bash
8gordon images <subcommand>
9```
10
11Subcommands:
12
13- `list` - List runtime images and registry tags.
14- `prune` - Prune dangling runtime images and old registry tags.
15- `tags` - List registry tags for a specific repository.
16
17> **Note:** Images commands require remote mode (`--remote` + `--token`, or configured remotes).
18
19## gordon images list
20
21```bash
22gordon images list
23gordon images list --json
24```
25
26Shows image rows with repository, tag, size, creation time, image id, and dangling status.
27Rows that exist only in the registry (not currently present in the runtime cache) are included with unavailable runtime fields shown as `-`.
28
29Flags:
30
31| Flag | Description |
32|------|-------------|
33| `--json` | Output images as JSON |
34
35### JSON Output
36
37```bash
38gordon images list --json
39```
40
41```json
42[
43  {
44    "repository": "myapp",
45    "tag": "latest",
46    "size": "148MB",
47    "created_at": "2026-03-13T10:15:00Z",
48    "image_id": "sha256:abc123def456",
49    "dangling": false
50  }
51]
52```
53
54## gordon images prune
55
56```bash
57gordon images prune [--dry-run] [--keep-releases <n>] [--dangling] [--registry] [--no-confirm]
58```
59
60By 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.
61
62A prune only ever deletes resources it can positively prove safe. Every other candidate is reported as `protected` or `unknown` and left in place; the command still succeeds. See [Prune safety](#prune-safety).
63
64Flags:
65
66| Flag | Default | Description |
67|------|---------|-------------|
68| `--dry-run` | `false` | Run the full inventory and planning, then report; nothing is deleted |
69| `--keep-releases` | `3` | Number of previous non-`latest` tags to keep per repository (`latest` is always preserved) |
70| `--dangling` | `false` | Restrict scope to dangling runtime images only |
71| `--registry` | `false` | Restrict scope to registry tag retention only |
72| `--no-confirm` | `false` | Skip the confirmation prompt |
73
74### Scope resolution
75
76- **No scope flags** (default): both runtime and registry cleanup run.
77- **`--dangling`**: only runtime dangling images are pruned; registry is skipped.
78- **`--registry`**: only registry tag retention runs; runtime is skipped.
79- **`--dangling --registry`**: both scopes run (same as default, but explicit).
80
81### Retention semantics
82
83- `latest` is always preserved when present.
84- `--keep-releases` counts non-`latest` tags, ordered by most recent first.
85- A tag named by durable app state survives beyond the retention window.
86- `--keep-releases=0` skips registry tag and blob cleanup entirely; dangling runtime prune still runs.
87
88## Prune safety
89
90Gordon prunes by ownership, not by name or age. Each candidate gets one verdict:
91
92| Verdict | Meaning |
93|---------|---------|
94| `eligible` | Every fact needed to prove the resource safe was read completely, and no durable record claims it. It is deleted. |
95| `protected` | A durable fact claims it: a desired or active app service (including stopped apps), a recovery inhibition, a staged or committed apply intent, an unfinished operation journal entry, container use, a pending upload, an ownership record, or the OCI closure of any of those. It survives. |
96| `unknown` | A fact needed to prove it safe was missing, unreadable, or unsupported. It survives. |
97
98Runtime images used by any container, running or stopped, always survive. Registry blobs reachable from a retained or protected manifest survive, including blobs shared with another tag. When a retained manifest cannot be read, the blobs whose safety depended on it become `unknown` rather than eligible.
99
100Both `--dry-run` and the executed prune return the same report: the verdict counts, the deleted identities, any deletion failures, every inventory gap, and the skipped candidates with their reason codes. A prune that deletes nothing is a success.
101
102## gordon images tags
103
104```bash
105gordon images tags <repository>
106gordon images tags <repository> --json
107```
108
109Lists all tags in the Gordon registry for the specified repository.
110
111Flags:
112
113| Flag | Description |
114|------|-------------|
115| `--json` | Output repository and tags as JSON |
116
117### JSON Output
118
119```bash
120gordon images tags myapp --json
121```
122
123```json
124{
125  "repository": "myapp",
126  "tags": ["latest", "v1.2.0", "v1.1.0"]
127}
128```
129
130## Examples
131
132```bash
133# List images
134gordon images list
135
136# Prune everything with defaults (dangling + registry, keep latest + 3)
137gordon images prune
138
139# List tags for a repository
140gordon images tags myapp
141
142# Prune dangling runtime images only
143gordon images prune --dangling
144
145# Prune registry tags only, keeping latest + 5 previous
146gordon images prune --registry --keep-releases 5
147
148# Inspect what prune would remove without applying
149# (also lists every skipped candidate with its reason)
150gordon images prune --dry-run
151
152# Skip confirmation prompt
153gordon images prune --no-confirm
154```
155
156## Required Permissions
157
158- The `list` subcommand requires `admin:status:read`.
159- The `prune` subcommand requires `admin:config:write`.
160- The `tags` subcommand requires `admin:status:read`.
161
162## Related
163
164- [CLI Commands](./index.md)
165- [Images Configuration](../config/images.md)