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
62Flags:
63
64| Flag | Default | Description |
65|------|---------|-------------|
66| `--dry-run` | `false` | Show prune behavior without applying changes |
67| `--keep-releases` | `3` | Number of previous non-`latest` tags to keep per repository (`latest` is always preserved) |
68| `--dangling` | `false` | Restrict scope to dangling runtime images only |
69| `--registry` | `false` | Restrict scope to registry tag retention only |
70| `--no-confirm` | `false` | Skip the confirmation prompt |
71
72### Scope resolution
73
74- **No scope flags** (default): both runtime and registry cleanup run.
75- **`--dangling`**: only runtime dangling images are pruned; registry is skipped.
76- **`--registry`**: only registry tag retention runs; runtime is skipped.
77- **`--dangling --registry`**: both scopes run (same as default, but explicit).
78
79### Retention semantics
80
81- `latest` is always preserved when present.
82- `--keep-releases` counts non-`latest` tags, ordered by most recent first.
83- `--keep-releases=0` with registry scope enabled still runs registry cleanup but keeps no non-`latest` tags.
84
85## gordon images tags
86
87```bash
88gordon images tags <repository>
89gordon images tags <repository> --json
90```
91
92Lists all tags in the Gordon registry for the specified repository.
93
94Flags:
95
96| Flag | Description |
97|------|-------------|
98| `--json` | Output repository and tags as JSON |
99
100### JSON Output
101
102```bash
103gordon images tags myapp --json
104```
105
106```json
107{
108  "repository": "myapp",
109  "tags": ["latest", "v1.2.0", "v1.1.0"]
110}
111```
112
113## Examples
114
115```bash
116# List images
117gordon images list
118
119# Prune everything with defaults (dangling + registry, keep latest + 3)
120gordon images prune
121
122# List tags for a repository
123gordon images tags myapp
124
125# Prune dangling runtime images only
126gordon images prune --dangling
127
128# Prune registry tags only, keeping latest + 5 previous
129gordon images prune --registry --keep-releases 5
130
131# Preview cleanup without applying
132gordon images prune --dry-run
133
134# Skip confirmation prompt
135gordon images prune --no-confirm
136```
137
138## Required Permissions
139
140- The `list` subcommand requires `admin:status:read`.
141- The `prune` subcommand requires `admin:config:write`.
142- The `tags` subcommand requires `admin:status:read`.
143
144## Related
145
146- [CLI Commands](./index.md)
147- [Images Configuration](../config/images.md)