---
title: "Change a value with an overlay"
description: "Append a change to an overlay file with aontu model set, so the original document keeps its bytes and a bad change is refused before it lands."
source: "https://aontu.dev/how-to/change-a-value-with-an-overlay/"
---

# Change a value with an overlay

Append a change to an overlay file with aontu model set, so the original document keeps its bytes and a bad change is refused before it lands.

Rendered from [`docs/how-to/change-a-value-with-an-overlay.md`](https://github.com/aontu-lang/aontu/blob/main/docs/how-to/change-a-value-with-an-overlay.md) in the engine repository, where a correction belongs, and where the test suite executes every example on this page.

Use `aontu model set` to append a change to an _overlay_, a second document unified with the entry. The command checks the proposed change before writing it and preserves the entry file. Write `system.aon`:

```aontu
services: { &: { replicas: *1|integer tier: *standard|string } }
services: auth: replicas: 3
services: billing: tier: premium
```

Now raise billing’s replicas without opening the file:

```sh
$ aontu model set '$.services.billing.replicas=2' --entry system.aon --overlay overlay.aon
verdict: valid
wrote: overlay.aon
```

The command creates a missing overlay. The file contains one assignment written as a chain of keys:

```aon
services: billing: replicas: 2
```

The entry and the overlay together are the changed document. Unification is order-independent, so appending to a second file means the same thing as writing into the first; to consume both, write an `all.aon` that loads them:

```aontu
@"./system.aon"
@"./overlay.aon"
```

```sh
$ aontu all.aon
{
  "services": {
    "auth": {
      "replicas": 3,
      "tier": "standard"
    },
    "billing": {
      "replicas": 2,
      "tier": "premium"
    }
  }
}
```

Billing overrides its `*1` default; auth keeps its pin. Overriding a default is the case `set` handles cleanly, because a default invites a concrete peer. A pinned value does not:

```sh
$ aontu model set '$.services.auth.replicas=5' --entry system.aon --overlay overlay.aon
verdict: invalid

$.services.auth.replicas: scalar_value [conflict]
  [aontu/scalar_value]: Cannot unify values at path $.services.auth.replicas
  data: overlay.aon:2:33 (5)
  schema: system.aon:2:27 (3)
$ echo $?
1
```

The overlay is written only when the change holds, so this refusal leaves its contents unchanged. The finding names the site doing the pinning (`system.aon:3:24`, which [`aontu why`](https://aontu.dev/how-to/explain-a-value) will list as a contribution) and to rewrite that literal rather than contradict it, [change the pinned value](https://aontu.dev/how-to/change-a-pinned-value).

`--dry-run` writes nothing either way and prints what would have been written; exit codes are [`aontu vet`](https://aontu.dev/docs/reference-api#aontu-vet)’s verdict classes, so the verb gates automation on its own. Keep the overlay _outside_ the entry’s include graph: an entry that loads its own overlay counts every change twice. The flag-by-flag contract is under [`aontu set`](https://aontu.dev/docs/reference-api#aontu-model-set), and the live version is [use-cases/08-feature-flags](https://aontu.dev/use-cases/08-feature-flags), where an ops overlay is written by `set --in-place` and never by hand, and repeated writes of one path leave one line.