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.
14- `prune` - Prune dangling runtime images and optionally registry data.
15
16> **Note:** Images commands require remote mode (`--remote` + `--token`, or configured remotes).
17
18## gordon images list
19
20```bash
21gordon images list
22```
23
24Shows image rows with repository, tag, size, creation time, image id, and dangling status.
25
26## gordon images prune
27
28```bash
29gordon images prune [--dry-run] [--keep <n>] [--runtime-only]
30```
31
32Flags:
33
34| Flag | Default | Description |
35|------|---------|-------------|
36| `--dry-run` | `false` | Show prune behavior without applying changes |
37| `--keep` | `0` | Number of latest tags to keep per repository (`0` disables registry cleanup) |
38| `--runtime-only` | `false` | Prune dangling runtime images only; forces registry cleanup off |
39
40`--keep` defaults to `0` for ad-hoc CLI safety (registry cleanup off by default), while scheduled pruning uses `images.prune.keep_last` from config (default `3`). Use config for recurring behavior; when a CLI `--keep` value is provided, that request value is used.
41
42Behavior notes:
43
44- `--runtime-only` forces `keep_last = 0`.
45- `--keep` must be `>= 0`.
46- `--dry-run` reports what would be pruned.
47
48## Examples
49
50```bash
51# List images
52gordon images list
53
54# Prune dangling runtime images only
55gordon images prune --runtime-only
56
57# Prune runtime images and keep 3 newest tags per repository
58gordon images prune --keep 3
59
60# Preview cleanup without applying
61gordon images prune --dry-run --keep 5
62```
63
64## Required Permissions
65
66- `list` requires `admin:status:read`.
67- `prune` requires `admin:config:write`.
68
69## Related
70
71- [CLI Commands](./index.md)
72- [Images Configuration](../config/images.md)