Quick Start

You need a Matomo site you are allowed to change, plus:

MATOMO_URL           Matomo base URL, for example https://matomo.example.com
MATOMO_TOKEN_AUTH    API token
MATOMO_SITE_ID       numeric site id

validate, plan, apply, and import call Matomo. They fail without those variables and a reachable instance. Credentials never belong in YAML.

From an extracted release archive or a v0.1.0 checkout:

cp examples/agoraform.yaml agoraform.yaml

Windows PowerShell:

Copy-Item .\examples\agoraform.yaml .\agoraform.yaml

The example declares one matomo.goal:

apiVersion: agoraform.io/v1alpha1
resources:
  - address: matomo.goal.trial_started
    attributes:
      name: Trial Started
      matchAttribute: event_action
      pattern: trialStarted

Then:

agoraform validate
agoraform plan      # expect a create; exit code 2 when changes exist
agoraform apply
agoraform plan      # no changes; exit code 0

Successful apply writes the Matomo goal id to agoraform.state.json next to the manifest. Do not put tokens in it, and do not commit it unless you have an explicit sharing workflow.

Import an existing goal

agoraform import matomo.goal.trial_started 12

Import prints YAML for configurable fields and records the remote id in local state. It does not rewrite agoraform.yaml and does not change Matomo. Paste the printed resource into the manifest, then agoraform plan should report no changes if the live goal still matches.