Snapshots

xmatix snapshot orchestrates whole-repository operations by re-invoking the per-kind pull and push verbs in sequence — one command to mirror the live tenant onto disk, one command to push the disk state back. It is the engine under migrate and the workhorse of release-time capture.

xmatix snapshot export                       # pull metadata + automation + analytics
xmatix snapshot export --scope TenantFull
xmatix snapshot export --skip dashboards,reports

xmatix snapshot import                       # push every JSON/CSX in the canonical folders
xmatix snapshot import --dry-run             # preview only — prints what would be pushed
xmatix snapshot import --skip metadata

Export

snapshot export runs, in order: metadata pull (with --scope, default TenantOwned), scripts pull, rules pull, workflows pull, dashboards pull, reports pull. Each writes into its canonical folder under xmatix/ (see the workspace layout). After an export, the on-disk tree mirrors the live tenant — git status then shows exactly what changed in the product since the last export, which is the entire trick behind snapshot-based drift detection: export on a schedule, and a non-empty diff is a finding.

Import and push order

snapshot import pushes every artifact file in a conservative order, so referenced rows exist before their consumers:

metadata — entities, fields, views and the rest of the model
Automation: scripts, then rules, then workflows
Analytics: dashboards, then reports

If an individual push fails, the snapshot continues with the remaining files and kinds, then exits with a non-zero aggregate code — so one bad file neither hides behind an early abort nor sneaks through a green build. --dry-run lists what would be pushed without sending anything.

Skip kinds

Both verbs accept a comma-separated --skip list drawn from: metadata, scripts, rules, workflows, dashboards, reports. Typical uses: --skip metadata when the model is managed by a different pipeline, or --skip dashboards,reports when analytics are owned in-product and only automation is under source control.

Common questions

How often should a team export?

At every deliberate change, plus on a schedule. The deliberate exports keep the repo authoritative; the scheduled one (nightly is common) catches in-product changes nobody exported — surfacing them as a reviewable diff while the author still remembers making them. The CI recipes page shows the scheduled variant as a drift gate.

Is import idempotent?

Effectively, yes — every push is an upsert, so importing a tree that matches the server changes nothing, and importing twice is the same as importing once. That is what makes snapshot import safe as a pipeline step: reruns after a partial failure simply converge the tenant toward the repo state.

Why did my import half-succeed?

Because import deliberately continues past failures — check the output for the per-file failures and the non-zero exit. Common causes are ordering across tenants (a rule referencing an entity that only exists at the source — push metadata first, which import already does; but a --skip metadata import can strand automation) and scripts whose new version fails server-side compile. Fix the named files and re-run; idempotency makes the retry safe.