# agility verify

> Source: https://agilitycms.com/docs/developers/cli-verify

`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](/docs/developers/cli-reference).

## Usage

```bash
agility verify --sourceGuid=<source> --targetGuid=<target> [options]
```

From `agility verify --help`:

```text
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.

## Options

`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](/docs/developers/cli-reference#options-shared-by-every-command) |

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.

## What it checks

| 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.

## How a run works

1. **Waits for the instances to be idle.** If either instance has a content update in progress, in preview or live mode, verify waits for it to finish, for up to 10 minutes.
2. **Pulls both instances in full** into `agility-files/`, replacing the local copies there.
3. **Checks again.** If an update ran during the pull, it pulls once more. If that happens a second time, it stops with exit code `2` and asks you to re-run once the instances are idle.
4. **Compares** the two pulls and prints the report.

## Reading the result

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.

## Exit codes

| 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 |

## Examples

```bash
# 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:

```bash
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
```

## Things to watch

- Let the target finish publishing before you verify. The status check waits for updates that are in progress, but a publish you start during the run will make it pull twice or stop.
- A full pull of two large instances takes time. Scope it with `--locales`, `--models`, `--pages` or `--containers` when you only changed part of the instance.
- Verify reports what's there. It doesn't fix anything: run a sync, or edit the target, then verify again.

## Related

- [sync and push](/docs/developers/cli-sync)
- [reverse-sync](/docs/developers/cli-reverse-sync)
- [Known issues and limits](/docs/developers/cli-reference#known-issues-and-limits)

---

## Related pages

- [Content Fetch API](https://agilitycms.com/docs/developers/content-fetch-api.md)
- [Content Sync API](https://agilitycms.com/docs/developers/content-sync-api.md)
- [Content Management API](https://agilitycms.com/docs/developers/content-management-api.md)
- [GraphQL API](https://agilitycms.com/docs/developers/graphql-api.md)
- [CLI - CI/CD Integration Guide](https://agilitycms.com/docs/developers/cli-ci-cd-integration-guide.md)
- [Testing on Swagger](https://agilitycms.com/docs/developers/testing-on-swagger.md)
- [GraphQL & Rest API Filtering](https://agilitycms.com/docs/developers/graphql-operators.md)
- [AgilityCLI (Command Line Interface)](https://agilitycms.com/docs/developers/cli.md)
- [Personal Access Tokens](https://agilitycms.com/docs/developers/personal-access-tokens.md)
- [Content Delivery & CDN Architecture](https://agilitycms.com/docs/developers/content-delivery-and-cdn-architecture.md)
- [Image Transformation Reference](https://agilitycms.com/docs/developers/image-transformation-reference.md)
- [Fetch API Status Codes and Caching](https://agilitycms.com/docs/developers/fetch-api-status-codes-and-caching.md)
- [Field Types and What the APIs Return](https://agilitycms.com/docs/developers/field-types-api-reference.md)
- [Content Sync Explained](https://agilitycms.com/docs/developers/content-sync-explained.md)
- [Agility CLI Command Reference](https://agilitycms.com/docs/developers/cli-reference.md)
- [CLI Reference: agility pull](https://agilitycms.com/docs/developers/cli-pull.md)
- [CLI Reference: agility sync and push](https://agilitycms.com/docs/developers/cli-sync.md)
- [CLI Reference: agility reverse-sync](https://agilitycms.com/docs/developers/cli-reverse-sync.md)
- [CLI Reference: agility workflows](https://agilitycms.com/docs/developers/cli-workflows.md)
- [CLI Reference: agility login and logout](https://agilitycms.com/docs/developers/cli-login-logout.md)
- [Test Your Agility Integration in CI](https://agilitycms.com/docs/developers/test-agility-integration-in-ci.md)
- [Create a Personal Access Token](https://agilitycms.com/docs/developers/create-personal-access-token.md)

Index of every docs page: https://agilitycms.com/docs/llms.txt