Skip to main content
The image command manages local image overrides for the active sitectl context. Use sitectl image set when you want a local site to run a different image tag, image reference, or build argument without editing the upstream template files directly.
sitectl image set currently requires a local context with a project directory. It writes docker-compose.override.yml in that project. Set, update, and clear operations patch only the relevant service image or nested build-argument lines; comments, anchors, formatting, and unrelated downstream override keys are preserved. Use sitectl image clear to remove image and build-arg override keys without deleting unrelated local override content:
With no service arguments, clear removes image/build-arg overrides for every service in the override file. With service arguments, it clears only those services.

​
Flags

--tag works for services known to sitectl’s shared LibOps image map, including the supported application services. A known buildable application service rejects --image, because leaving its Compose build definition in place would make the runtime image ambiguous. Use --tag or --build-arg SERVICE.BASE_IMAGE=... for those services. Use --image for dependency services that do not build locally. These are local overrides, not lockfile updates. A tag-only override deliberately stops using the tracked Compose digest for that service. For a reproducible test, pass a full tag@sha256:digest reference with --image for a non-buildable service or with --build-arg SERVICE.BASE_IMAGE=... for a buildable application. Before promotion, update a direct dependency’s tracked tag and digest through a reviewed dependency bump, or commit the tested BASE_IMAGE=tag@sha256:digest default in the downstream Dockerfile/main Compose file. The ignored override file is not a production lock.

​
Compose Reconcile

Image overrides participate in the first-run sitectl compose up reconcile contract:
  • an explicit image override for a non-buildable service means core does not require the plugin’s default image to exist locally
  • a build-arg override triggers the build phase so the new arguments are applied
  • the override file fingerprint is part of the local reconcile cache key
After changing overrides, run:
If you clear a build-arg override and want to rebuild with the default image metadata immediately, run:
See Compose reconcile contract for the contributor-facing contract.

​
Reference

Manage Compose image overrides for a site
Write Compose image or build-arg overrides
Remove Compose image and build-arg overrides