1.4 Editing, history and promotion

Included from Basic tier

After this you can: edit a stored document with compare-and-set, read its version history, and promote a locally authored document onto the server.

Before you start — tick each one:

• Lesson 1.3 — Properties and settings: the overlay (opschain learn 1.3)

In the GUI: the Properties and Settings tabs on a node page edit the same documents through the same compare-and-set endpoints the CLI uses.

Lesson 1.3 wrote one property with properties edit. This lesson is about what that write really did: a new version in a trail nothing overwrites, guarded so two people can never silently clobber each other — and the flow that turns state a local run discovered into a file you commit.

1. Version history

Every edit to a stored properties or settings document is a new version — nothing is overwritten. history lists the trail, show reads any point on it:

opschain properties history acme

VERSION  CREATED
2        2026-11-07T00:41:03Z
1        2026-11-07T00:40:12Z

opschain properties show acme --version 1

path:       /projects/acme
id:         01a1b3a0-…
version:    1
created_at: 2026-11-07T00:40:12Z
data:
{}

opschain settings show|history are the settings twins. Each change also pins the property versions it ran with, so "what did the estate look like when this deployed" stays answerable forever.

2. Editing with compare-and-set

edit replaces a stored document's data wholesale, as a new version (lesson 1.3): the file is the complete new data, JSON or YAML — fetch the current data with show first, edit it, and send it back:

opschain properties edit acme -f props.yaml

updated properties of /projects/acme: version 2 → 3

The write is versioned compare-and-set: the command reads the current version and writes against it, so an edit that landed in between is a named conflict, never a silent clobber:

Error: the document changed while you edited it (your edit was based on version 2; the server now holds version 3) — re-run the edit

Re-fetch, reapply your change and retry. --base-version N skips the read and asserts your edit was made against exactly version N — the same conflict if N is stale. opschain settings edit is the settings twin.

3. The local promotion flow

On the local lane (lesson 2.1), a run can write properties back into the local store from inside a step — discovered state:

# .opschain/actions/discover.yaml
action: discover
steps:
  - name: record
    run: opschain step set-property environment app.endpoint https://dev.acme.example

After opschain runs create change discover --env dev --local, the value sits in the local store's environment layer, shadowing whatever the repository's properties file says. opschain properties export promotes it into the git-committed repository layer, as a three-step ratchet. export and reset are repository-scoped verbs that run on your machine, so like every verb of this lane they take --local: with a server context active (opschain context use, lesson 0.2) the CLI refuses them by name until you say which lane you mean.

opschain properties export --env dev --local

/projects/myrepo/environments/dev → .opschain/properties/projects/myrepo/environments/dev/properties.json
+ app = map[endpoint:https://dev.acme.example]
diff only — re-run with --apply to write the file

opschain properties export --env dev --apply --prune --local

/projects/myrepo/environments/dev → .opschain/properties/projects/myrepo/environments/dev/properties.json
+ app = map[endpoint:https://dev.acme.example]
applied; DB layer pruned as version 2 (history retained) — review and commit .opschain/properties/projects/myrepo/environments/dev/properties.json

• The default is a diff — what materialising the layer would change.
• --apply writes the properties.json file for you to review and commit via git.
• --prune additionally empties the exported keys out of the database layer (as a new version, reversible), handing authority to git — the recommended promotion, since otherwise the local layer keeps shadowing the file.

opschain properties reset drops a local database layer back to empty as a new version — the development-loop reset; history stays readable:

opschain properties reset --env dev --local

/projects/myrepo/environments/dev: DB property layer reset as version 3 (history and per-step pins retained)

Both verbs target the project layer by default, --env <e> for an environment, --env <e> --asset <a> for an asset. Once the file is committed and pushed, it is the repository layer every server run of that project merges underneath its stored layers (lesson 1.3).

Check yourself

• What happens to properties edit when someone else saved a newer version while you were editing?

What you learned

• Every edit is a new version; history lists the trail and show --version N reads any point on it.
• properties edit is compare-and-set: a concurrent edit is a named conflict to re-fetch and retry, never a silent overwrite.
• step set-property records discovered state in the local layer; properties export --apply --prune promotes it into a file you commit and hands authority to git.
• properties reset empties a local layer as a new, reversible version.

Next: lesson 1.5 — The licence behind the limits (opschain learn 1.5), or back to your track (opschain learn).