opschain properties export

Included from Basic tier

opschain properties export [--project | --env <code> [--asset <code>]] [--apply [--prune]]

Materialises a target node's database property layer into the matching .opschain/properties/.../properties.json file of the local repository — the "discovered state → authored state" promotion flow. Local runs accumulate properties in a per-user database layer; this command turns that layer into an authored file you review and commit via git. Repo-scoped: it runs in the repository and has no remote form.

It is a three-step ratchet:

1. Diff (default). Prints what the DB layer adds or changes over the file, writes nothing.
2. --apply. Writes the file for review and commit via git. The DB layer still exists and still shadows the file.
3. --apply --prune. Additionally removes the exported keys from the DB layer as a new version (reversible via history), handing authority for them to git — recommended, since otherwise the next in-flight update silently shadows the file again.

Flags

Flag	Meaning
--project	Target the project layer (the default).
--env <code>	Target an environment layer.
--asset <code>	Target an asset layer (requires --env).
--apply	Write the properties file.
--prune	With --apply: remove the exported keys from the DB layer as a new version.

Output

Added keys print as + <path> = <value>, changed keys as ~ <path> = <new> (was <old>), then a status line:

opschain properties export --env dev --apply --prune
/projects/demo/environments/dev → .opschain/properties/projects/demo/environments/dev/properties.json
+ opschain.env.REGION = ap-southeast-2
applied; DB layer pruned as version 3 (history retained) — review and commit .opschain/properties/projects/demo/environments/dev/properties.json

A clean layer prints <node>: nothing to export — the DB layer adds nothing over <file>; a diff-only run ends with diff only — re-run with --apply to write the file; an unpruned apply ends with a reminder that without --prune the DB layer still shadows it. With -o json / -o yaml the whole result is a machine document.

Exit codes

Code	Meaning
0	Diffed or exported.
1	The export failed (unreadable store, unresolvable target).
2	Usage error.

Named errors

• --prune requires --apply (exit 2).
• --project and --env are mutually exclusive (exit 2).
• --asset requires --env (exit 2).
• exporting properties is repo-scoped and runs locally — it has no remote form; run it in the repository (or pass --local) — a server target is active (exit 1).
• <files> exists at this layer — export writes <layer-folder>/properties.json, which it would shadow (it merges over the json file); merge or remove it first — the layer folder holds other properties files that would merge over the exported one (exit 1).

See also

• opschain docs cli/properties-reset — drop the DB layer without exporting.
• opschain learn 1.3 — properties and settings, guided.