What is your developer-dependent CMS actually costing you? Calculate your costs and get a full report
What is your developer-dependent CMS actually costing you? Calculate your costs and get a full report
APIs
agility verify compares a synced target instance with its source and reports every difference, without writing to either. Options, what it checks, severities, exit codes and CI examples, for CLI 1.2.1.
agility verify checks that a synced target instance matches its source. It pulls both instances fresh, compares them, and reports every difference it finds. It's a separate check from the sync's own log: it doesn't reuse the sync's code to decide what should match, so a sync that reported success can still be checked independently. It never writes to either instance or to the mapping files.
Checked against @agility/cli 1.2.1 (verify is new in 1.2.0). For sign-in and the files the CLI writes, see the CLI command reference.
agility verify --sourceGuid=<source> --targetGuid=<target> [options]
From agility verify --help:
agility verify
Compare a synced target instance against its source (fresh full pull of both)
and report every difference. Exit code 0 = match, 1 = differences found, 2 =
could not verify. Never writes to either instance or to the mapping files.
Pass the same --sourceGuid and --targetGuid you used for the sync, and run it from the folder that holds that sync's agility-files/mappings/. Verify uses the mappings to pair each source item with its target item.
verify has its own, smaller set of options. Options that only make sense for a sync, such as --overwrite, --autoPublish and --preflight, aren't listed in its --help and have no effect.
| Option | Default | What it does |
|---|---|---|
--sourceGuid | from .env | The source instance of the sync being verified. Falls back to AGILITY_GUID in a .env file |
--targetGuid | from .env | The target instance of the sync being verified. Falls back to AGILITY_TARGET_GUID in a .env file |
--locales | auto-detected | Comma-separated locale codes. Each one needs mappings from an earlier sync |
--channel | every channel | Checks only this channel's sitemap |
--models | none | Verifies only these models, the way sync --models scopes a sync |
--pages | none | Verifies only these pages and what they need (paths, names or page IDs) |
--containers | none | Verifies only these containers and what they depend on (reference names, titles or IDs) |
--jsonSummary | agility-files/logs/verify-<source>-<target>-<timestamp>.json | Where to write the full report |
--token, --headless, --verbose, --dev | The same as on every other command. See the command reference |
Pass only one of --models, --pages and --containers. Combining them stops the run with exit code 2. A scoped verify still pulls both instances in full, because it needs complete data to resolve references.
| Area | What's compared |
|---|---|
| Content | Item counts per model and container, list order, and field values, with linked content and assets resolved through the mappings |
| Pages | Component order and zone placement on every page |
| Sitemap | The page tree and its order, per locale and channel |
| Structure | Models, containers, page models, assets and galleries |
| Mappings | That every mapping record points at an item that exists, and that no two source items map to the same target |
Models, containers, page models, assets and galleries are checked once for the instance. Content, pages and the sitemap are checked for each locale.
agility-files/, replacing the local copies there.2 and asks you to re-run once the instances are idle.Each difference is a finding with one of three severities:
| Severity | Meaning | Fails the run? |
|---|---|---|
| Failure | The target differs from the source in a way the sync should have prevented | Yes |
| Warning | Worth knowing, such as extra items on the target or a different publish state | No |
| Source defect | A difference the source item explains, such as a missing required field the target would reject | No |
The console report groups findings by severity and category and shows up to 20 of each, with a link to the item in the Agility app. The JSON report has every finding, plus per-locale counts of what was checked, matched, mismatched, missing and extra.
| Code | Meaning |
|---|---|
0 | The target matches the source. Warnings and source defects don't change this |
1 | At least one failure was found |
2 | Verify couldn't produce a result: sign-in failed, the GUIDs were missing or identical, there are no mappings for the pair or a requested locale, a pull failed, or an update kept running during the pull |
# Verify everything the sync covered
agility verify --sourceGuid="abc123-u" --targetGuid="def456-u"
# One locale, with the report written where CI can pick it up
agility verify --sourceGuid="abc123-u" --targetGuid="def456-u" \
--locales="en-us" --headless --jsonSummary=reports/verify.json
# Only the pages under /products
agility verify --sourceGuid="abc123-u" --targetGuid="def456-u" --pages="/products"
A CI step that syncs, then fails the job if the target doesn't match:
set -e
npx @agility/cli@1.2.1 sync --sourceGuid="$SOURCE" --targetGuid="$TARGET" --headless \
--jsonSummary=reports/sync.json
npx @agility/cli@1.2.1 verify --sourceGuid="$SOURCE" --targetGuid="$TARGET" --headless \
--jsonSummary=reports/verify.json
--locales, --models, --pages or --containers when you only changed part of the instance.