> ## Documentation Index
> Fetch the complete documentation index at: https://sitectl.libops.io/llms.txt
> Use this file to discover all available pages before exploring further.

# image

> Manage local Docker Compose image and build-arg overrides.

export const Compose = () => <Tooltip headline="Compose" tip={<>
        Docker Compose is Docker's tool for defining and running multi-container applications.{" "}
        <a href="https://docs.docker.com/compose/">https://docs.docker.com/compose/</a>.
      </>}>
    <>
      <Icon icon="docker" />
      {" "}
      Compose
    </>
  </Tooltip>;

The `image` command manages local <Compose /> 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.

```bash theme={null}
sitectl image set --tag wp=nginx-1.30.3-php84
sitectl image set --image app=ghcr.io/example/app:pr-123
sitectl image set --build-arg app.BASE_IMAGE=libops/app:php84
```

`sitectl image set` currently requires a local context with a project directory. It writes `docker-compose.override.yml` in that project.

Use `sitectl image clear` to remove image and build-arg override keys without deleting unrelated local override content:

```bash theme={null}
sitectl image clear
sitectl image clear wp
```

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

| Flag          | Format              | Use                                                     |
| ------------- | ------------------- | ------------------------------------------------------- |
| `--tag`       | `SERVICE=TAG`       | Set a known LibOps service to a published LibOps tag.   |
| `--image`     | `SERVICE=IMAGE`     | Set any Compose service to an explicit image reference. |
| `--build-arg` | `SERVICE.ARG=VALUE` | Set a Compose build argument for a service.             |

`--tag` only works for services known to sitectl's shared LibOps image map. For app-specific services, use `--image` or `--build-arg`.

## Compose Reconcile

Image overrides participate in the first-run `sitectl compose up` reconcile contract:

* an explicit image override for a 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:

```bash theme={null}
sitectl compose up
```

If you clear a build-arg override and want to rebuild with the default image metadata immediately, run:

```bash theme={null}
sitectl image clear wp
sitectl compose reconcile --force
```

See [Compose reconcile contract](/contributing/compose-reconcile) for the contributor-facing contract.

## Reference

Manage Compose image overrides for a site

```bash theme={null}
sitectl image <command>
```

Write Compose image or build-arg overrides

```bash theme={null}
sitectl image set
```

| Flag          | Default | Description                                                                                      |
| ------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `--build-arg` | `[]`    | Override a Compose service build arg as SERVICE.ARG=VALUE; may be passed more than once.         |
| `--image`     | `[]`    | Override a Compose service image as SERVICE=IMAGE; may be passed more than once.                 |
| `--tag`       | `[]`    | Set a LibOps image tag for a known Compose service as SERVICE=TAG; may be passed more than once. |

Remove Compose image and build-arg overrides

```bash theme={null}
sitectl image clear [SERVICE...]
```