Skip to main content
Every formae apply requires a mode. The mode determines what formae is allowed to do, and more importantly, what it won’t do.

​
Reconcile

Reconcile applies a complete desired declaration for each affected stack. It creates or updates declared resources and removes managed resources omitted from those stacks. Review the simulation before applying, especially deletions and replacements. A failed command can leave the cloud only partly updated. An explicitly declared stack with no resources has an empty desired resource set. Its existing managed resources are planned for deletion, even if the declaration keeps a generator. Stacks outside the declaration remain outside this reconcile. Use reconcile for everyday planned changes, whether the Pkl lives in a maintained project or is authored temporarily by your assistant. Without a codebase, the assistant retrieves the complete stack’s recorded desired state, edits it, and reconciles that stack. See Ways to work.

​
Patch

Patch is append-only. It only creates or updates the resources named in your forma, and never destroys anything. Resources you don’t mention are left untouched, and within a resource, collection properties (tags, security groups, and the like) are only added to, never trimmed. Reconcile can destroy; patch cannot. Patch exists for two situations:
  • Working without a declared codebase. When you don’t have code that describes the desired state of your infrastructure, or don’t have it to hand, you work by extract-and-patch: extract the resource or two you want to change, edit them, and apply them back with patch.
  • Emergency fixes. When you’re firefighting an incident and want the smallest possible blast radius, patch one or two resources to resolve it rather than reconciling a whole stack.

​
A patch is an out-of-band change

A patch changes your infrastructure without going through a full reconcile, so formae treats it exactly like a change made outside formae, the same way it treats an out-of-band change that sync pulls in. The patch updates actual state without automatically changing the reconcile baseline. The next soft reconcile on that stack presents the out-of-band changes for review. Absorb the patch if you want it to become recorded desired intent, or revert it. A 2am patch can resolve the incident immediately; the decision to keep it can wait until the next reconcile. If you maintain a codebase, the assistant updates the selected project after the decision is recorded.

​
Collection handling

When a resource has a collection property (tags, security groups, or any list of values), the apply mode determines how that collection is updated. Reconcile mode treats your forma as the complete truth: the collection after apply matches exactly what you specified, and elements not in your forma are removed. Patch mode is append-only: elements in your forma are guaranteed to exist after apply, but existing elements are never removed. Example: a resource has tags [A, B, C] and your forma specifies [B, D]. This makes patch mode safer for shared resources where multiple teams manage different parts of the same collection.

​
Hard vs soft reconcile

When someone changes a resource outside of formae (through the cloud console, another tool, or a script), that’s an out-of-band change. Reconcile mode handles them in two ways.

​
Soft reconcile (default)

When formae detects out-of-band changes that need a decision, it stops before applying and presents the changes for review. In an interactive CLI or assistant session, choose absorb or revert for every out-of-band change in the affected stack:
  • Absorb records the observed change as desired intent in a reconcile command.
  • Revert plans cloud operations to restore the declared desired state.
The final simulation includes those choices and any other changes you requested. Confirm that combined plan before it runs. Simulation alone never records an absorption. If relevant state changes after review, review the updated plan before submitting again. After resolution, formae prints extraction queries and deletion guidance for an optional codebase. The assistant maintains the selected project automatically. Another session sees the centrally recorded decision without needing those files. Noninteractive callers receive structured information about out-of-band changes; formae does not silently choose for them or force the apply.

​
Hard reconcile

If you’ve reviewed the changes and want to overwrite them, add --force:
Hard reconcile overwrites all out-of-band changes and brings the infrastructure exactly in line with your forma. Use it when your code is the authority and external changes should be discarded.
Soft reconcile is a safety net. Reach for --force only when you know what you’re overwriting.

​
Resource replacement

Most property changes update a resource in place. Some properties are immutable, though: changing them triggers a destroy followed by a create.
formae handles this automatically, but be aware: replacement means downtime for that resource and anything that depends on it. Simulation catches this before it happens:
Check the simulation output for “replace” operations before applying.

​
See also

  • Policy: auto-reconcile policies apply reconcile mode on a schedule.
  • Synchronization: how formae detects the out-of-band changes that soft reconcile protects against.