monoceros upgrade

Moves a workbench forward: the runtime base image, the service images, and everything a feature layer built. This is the deliberate step, the one you run when you want those to change.

Your features are not what you need this for. They are brought up to date by every apply. upgrade is for the parts that stay put until you say otherwise, because your data lives on them. See Reproducibility and upgrades.

monoceros upgrade                   # refresh every running workbench
monoceros upgrade <name>            # refresh one workbench
monoceros upgrade <name> <version>  # refresh one + pin its runtime to <version>
monoceros upgrade --list            # list available runtime versions, change nothing

What it does

For each targeted workbench, upgrade:

1. Rebuilds the feature layers from scratch (--build-no-cache), so everything a feature installed is fetched again: apt packages, interpreters, and any tool that has no per-apply refresh of its own.
2. Bumps the runtime base only when newer. Moves the pinned runtimeVersion to the latest published runtime if one exists; otherwise leaves it untouched. monoceros upgrade <name> <version> pins an exact version instead.
3. Brings the services up to the catalog and re-pulls their images. A service added from the catalog keeps the image tag it was created with, so a security fix upstream would otherwise never reach a workbench that already exists. upgrade writes the tag the catalog ships today into your yml, names every change in its output, and re-pulls the images, so a fix inside an unchanged tag lands too. It leaves an image you chose yourself untouched.

Afterwards it prunes stale Monoceros-built images (only images Monoceros recorded building - never anything else) and records the run, then prints a summary:

✔ Upgraded 'acme'
  layers    rebuilt - latest pulled
  base      1.1.0 (already latest)
  services  images re-pulled (1 retagged)
  pruned    0 removed (1 stale entry already gone)
  recorded  2026-06-10 17:38 UTC

The retag is the only thing upgrade writes into your services: block, and it logs each one as old image → new image. A curated service follows the catalog, including across a major version. If you were holding an older image on purpose, that log line is what you need to put it back. An unreachable registry does not fail the upgrade: the workbench starts from the cached images and warns you it did.

Scope

monoceros upgrade with no name is global: it refreshes every workbench that is currently running. Stopped or never-built workbenches are skipped (and listed) - upgrade never starts a stopped container or materializes a config that was only init-ed. To refresh one of those, name it explicitly: monoceros upgrade <name>.