plan

agoraform plan
agoraform plan -f path/to/manifest.yaml
agoraform plan path/to/manifest.yaml

Purpose

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

The default manifest is agoraform.yaml.

Plan loads and validates the manifest, configures registered providers with non-secret provider desired state, validates connectivity, reads local identity state, and then reads desired resources in dependency order.

Arguments

Argument	Description
[file]	Optional positional path to the manifest. At most one argument.

Specify a manifest as an argument or with --file, not both.

Flags

Flag	Description
-f, --file	Path to the Agoraform manifest (default agoraform.yaml)

Expected behavior

A missing unbound remote resource becomes a create. A bound identity missing remotely is a stale-state error rather than an implicit replacement. Provider normalizers may remove computed/default noise before diffing.

Unmanaged remote objects are ignored. Destructive deletion is not implemented.

Example resource changes:

Agoraform will perform the following actions:

+ matomo.goal.trial_started

    name: "Trial Started"
    matchAttribute: "event_action"
    pattern: "trialStarted"

Plan: 1 to create, 0 to update, 0 to destroy.

Example with Matomo publication:

Agoraform will perform the following actions:

~ matomo.tag.trial_started

    eventAction:
      "trialStart" -> "trialStarted"

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

Plan: 0 to create, 1 to update, 0 to destroy, 1 provider action.

Zero change:

No changes. Desired configuration matches live resources.

Plan: 0 to create, 0 to update, 0 to destroy.

The 0 to destroy counter is present in plan output even though destroy is not implemented.

Provider actions

Matomo Tag Manager publication is part of the reviewed plan, not a separate command. If managed Tag Manager draft resources already have planned changes and providers.matomo.publish is enabled, publication is shown as conditional. Apply rechecks the converged draft before creating a version.

A plan containing only a provider action still exits with code 2 because apply has work to do.

Permission and environment checks for Matomo publication happen during planning without creating a version.

Exit codes

Code	Meaning
0	Plan succeeded and no actions are required
1	Planning failed
2	Plan succeeded and resource or provider actions are present
3	Invalid invocation

Exit 2 is intended for CI/GitOps workflows that treat a non-empty plan as an actionable result rather than a failure.

Caveats

• Plan never calls provider mutation methods.
• Plan ignores remote objects that are not represented by the manifest or local state.
• Secrets are not written to plan output.