Lifecycle

Agoraform v0.3.0 mutations are create and update only. There is no destroy command, and apply does not delete remote resources.

Validate

agoraform validate loads the manifest and checks:

• YAML and apiVersion
• provider names and provider-specific configuration
• resource address syntax and duplicates
• $ref validity and dependency cycles
• registered provider and resource support
• provider connectivity
• provider-specific resource fields

It may contact providers. It does not mutate them.

Plan

agoraform plan compares desired manifest state with provider-reported remote state and prints deterministic actions. It is non-mutating.

A missing unbound remote resource becomes a create. A bound identity missing remotely is a stale-state error rather than an implicit replacement. Unmanaged remote objects are ignored.

Some desired states require provider-level convergence after resource CRUD. These actions are still part of the reviewed plan. Matomo Tag Manager publication can appear as:

> matomo.container.main: publish -> live [conditional]

Conditional provider actions still count as planned work. A plan containing only a provider action still exits with code 2.

Action	Meaning
create	Desired resource is absent remotely
update	Configurable attributes differ
unchanged	Desired and comparable remote state match
adopt	Google Ads customer conversion goals are created by Google Ads; Agoraform binds and reconciles them

Destructive deletion is not implemented.

Apply

agoraform apply builds the same reviewed plan and executes it:

1. Validate and configure providers
2. Build the resource and provider-action plan
3. Apply resource creates and updates in prerequisite-first order
4. Persist identities in agoraform.state.json
5. Run provider finalization (for example Matomo publication) only after every resource mutation succeeds

Failed mutations do not create new bindings. Provider finalization is not attempted after a resource or required state-persistence failure. Successful remote changes are not rolled back.

If a create succeeds but the state file cannot be written, re-bind with agoraform import after fixing the file. A later unchanged plan does not repair a missing binding.

Import

agoraform import ADDRESS REMOTE-ID reads one existing remote object, prints configurable YAML, and persists the identity. It never creates, updates, or deletes the remote resource and does not rewrite your manifest.

Import related Tag Manager triggers and variables before a tag so $refs can be reconstructed. Import a Google Ads conversion action before adding an optional conversionAction $ref on the matching customer conversion goal.

Local state

agoraform.state.json maps logical addresses to provider-native IDs:

{
  "version": 1,
  "resources": {
    "matomo.goal.trial_started": {
      "provider": "matomo",
      "remoteId": "12"
    }
  }
}

Plan reads bound objects by identity, not by mutable name. See project structure.