List

Lists all local caches used by Wendy: downloaded OS images and the per-app build caches (buildx/ and ocilayout/) that make warm rebuilds and chunk-diff deploys fast.

Pass --json to receive a JSON array on stdout instead of the human-readable output described below.

Output structure

• OS images (os-images/) — each image file is listed as a separate row prefixed os-images/.
• Build caches (buildx/ and ocilayout/) — each per-app sub-directory is listed as a separate row named <store>/<app-id>-<platform>, e.g. ocilayout/com.example.myapp-linux_arm64 (app ID and platform are lower-cased, with characters outside a-z, 0-9, - and . replaced by _). Build-cache rows also carry a last-built age. The root-level shared store inside each of these directories (blobs/, ingest/, index files) is folded into the summary line rather than listed, because it cannot be deleted without taking every app cache in that store down with it.
• Everything else — listed as a single top-level row.

Entries are sorted largest-first so the biggest reclaimable items are at the top, in both interactive and non-interactive output.

Build-cache sizes are per-link. Automatic maintenance hardlinks a layer shared by several apps into each of their directories. A per-row size (and the sizeBytes / size JSON fields) counts that layer once per link, so build-cache rows can sum past the real on-disk total. The summary line's "on disk" figure is the dedup-aware total — the same number the automatic size cap is enforced against.

When --json is not passed:

• In an interactive terminal (stdin and stdout are both TTYs), an interactive picker is shown listing all cached items. Build-cache entries show their last-built age alongside the size (e.g. 2.0 GB · built 3h ago); other entries show only the size. When build caches are present, a summary line showing real on-disk usage and the cap appears above the picker. Selected items can be removed.

• In a non-interactive context (pipe, CI, etc.), a plain text list is printed, one entry per line. Build-cache rows use the format <name> (<size>, built <age>); all other rows use <name> (<size>). When build caches are present, a summary line is printed after the list:

    ocilayout/com.example.myapp-linux_arm64  (2.0 GB, built 3h ago)
    os-images/wendyos-raspberry-pi-5-0.10.4.img  (4.5 GB)
  
  Build cache: 83.0 GB on disk (1.2 GB shared) · cap 100.0 GB

  "on disk" is the dedup-aware total; "shared" is the size of the root-level shared store (blobs/, ingest/) that is never evicted on its own; "cap" is the current size cap (see Automatic maintenance).

When the cache is empty (or the cache directory does not exist), the command prints Cache is empty. in human-readable mode, or an empty JSON array ([]) with --json.

JSON output

wendy cache list --json

Each element of the returned array represents one cached item. The summary line is not included in JSON output.

[
  {
    "name": "os-images/wendyos-raspberry-pi-5-0.10.4.img",
    "path": "/Users/you/Library/Caches/wendy/os-images/wendyos-raspberry-pi-5-0.10.4.img",
    "sizeBytes": 4831838208,
    "size": "4.5 GB"
  },
  {
    "name": "ocilayout/com.example.myapp-linux_arm64",
    "path": "/Users/you/Library/Caches/wendy/ocilayout/com.example.myapp-linux_arm64",
    "sizeBytes": 2147483648,
    "size": "2.0 GB",
    "lastBuilt": "3h ago"
  }
]

Note: path is a full local filesystem path and may include the current username or CI runner cache location. Redact it before forwarding command output to shared logs or support channels.

Returns [] when the cache is empty.

wendy os cache list --json

Each element represents one cached OS image file:

[
  {
    "name": "wendyos-raspberry-pi-5-0.10.4.img",
    "sizeBytes": 4831838208,
    "size": "4.5 GB"
  }
]

Returns [] when no cached OS images are found.

Automatic maintenance

The build caches are bounded automatically. After a wendy run deploy that exports through the persistent OCI layout (the chunk-diff path used with the Docker builder), Wendy:

1. Deduplicates content-identical layers across the buildx and ocilayout stores by hardlinking them, so a layer shared by several apps — or held in both stores — costs one copy instead of N.
2. Evicts whole per-app cache directories, least-recently-built first, until the dedup-aware on-disk total is at or under the size cap. Evicting a directory only frees a layer when it held the layer's last remaining link.
3. Bounds the builder's own store by running docker buildx prune --max-used-space against the OCI-export builder (best-effort, with a 60-second budget).

No manual action is needed. Maintenance is best-effort: a failure leaves the caches as they are for the next run to reclaim.

WENDY_BUILD_CACHE_MAX_BYTES

Set this environment variable (in bytes) to override the default size cap of 100 GiB. A value of 0 or a negative number disables eviction and the builder-store prune; deduplication still runs.

Eviction safety guards

A per-app cache directory is never evicted while it may be in use:

• Lock protection — a directory whose layout lock is held by another wendy process (for the whole of its build → read → push) is skipped, however old its contents look. It becomes eligible again once that process releases the lock.
• Active-window protection — a directory that a build wrote a layer into within the last 10 minutes is skipped as a likely in-progress build.
• Own build — the deploying process always pins its own app's directory.

wendy cache dedup

A hidden wendy cache dedup [--max <bytes>] command runs the same on-disk maintenance on demand, for manual reclaim or debugging. It is not shown in wendy cache --help because the automatic path is the intended one.

• --max sets the size cap for this run (defaults to WENDY_BUILD_CACHE_MAX_BYTES or 100 GiB). Pass 0 to deduplicate only, without evicting anything.
• It only ever deduplicates or deletes cache content, honours the same safety guards as automatic maintenance, and is safe to run at any time.
• It prints Deduplicated <size>, evicted <size>. on completion.