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 optionally registry data.

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

gordon images list

gordon images list

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 -.

gordon images prune

gordon images prune [--dry-run] [--keep <n>] [--runtime-only]

Flags:

Flag	Default	Description
`--dry-run`	`false`	Show prune behavior without applying changes
`--keep`	`0`	Number of previous tags to keep per repository (`latest` is always preserved when present; `0` disables registry cleanup)
`--runtime-only`	`false`	Prune dangling runtime images only; forces registry cleanup off

--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.

Behavior notes:

--runtime-only forces keep_last = 0.
--keep must be >= 0.
--dry-run reports what would be pruned.
When --keep is greater than 0, registry cleanup keeps latest (if present) plus the requested number of most-recent non-latest tags.

Examples

# List images
gordon images list

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

# Prune runtime images and keep latest + 3 previous tags per repository
gordon images prune --keep 3

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

Required Permissions

list requires admin:status:read.
prune requires admin:config:write.

source

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 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.
25Rows that exist only in the registry (not currently present in the runtime cache) are included with unavailable runtime fields shown as `-`.
26
27## gordon images prune
28
29```bash
30gordon images prune [--dry-run] [--keep <n>] [--runtime-only]
31```
32
33Flags:
34
35| Flag | Default | Description |
36|------|---------|-------------|
37| `--dry-run` | `false` | Show prune behavior without applying changes |
38| `--keep` | `0` | Number of previous tags to keep per repository (`latest` is always preserved when present; `0` disables registry cleanup) |
39| `--runtime-only` | `false` | Prune dangling runtime images only; forces registry cleanup off |
40
41`--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.
42
43Behavior notes:
44
45- `--runtime-only` forces `keep_last = 0`.
46- `--keep` must be `>= 0`.
47- `--dry-run` reports what would be pruned.
48- When `--keep` is greater than `0`, registry cleanup keeps `latest` (if present) plus the requested number of most-recent non-`latest` tags.
49
50## Examples
51
52```bash
53# List images
54gordon images list
55
56# Prune dangling runtime images only
57gordon images prune --runtime-only
58
59# Prune runtime images and keep latest + 3 previous tags per repository
60gordon images prune --keep 3
61
62# Preview cleanup without applying
63gordon images prune --dry-run --keep 5
64```
65
66## Required Permissions
67
68- `list` requires `admin:status:read`.
69- `prune` requires `admin:config:write`.
70
71## Related
72
73- [CLI Commands](./index.md)
74- [Images Configuration](../config/images.md)

images.md RawHistoryFolder