# agility sync and agility push

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

`agility sync` copies a source instance into a target instance: models, containers, content, page templates, pages, assets, galleries and URL redirections. It resolves dependencies so references point at the right items on the target, and it records source-to-target **mappings** so repeated runs update items instead of duplicating them. `agility push` is the same command under another name, with two small differences listed below.

Checked against `@agility/cli` 1.1.0. For the options every command shares, sign-in and exit codes, see the [CLI command reference](/docs/developers/cli-reference). For what a sync copies, conflicts and post-sync steps, see [Agility CLI](/docs/developers/cli).

## Usage

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

From `agility push --help`:

```text
agility push

Push your instance using the new 2-pass dependency system.
```

The top-level help lists the command as `agility push` with `[aliases: sync]`.

## sync or push?

Both run the same pipeline: pull the source, pull the target, compare, then write to the target. In 1.1.0 they differ in two ways:

| | `sync` | `push` |
| --- | --- | --- |
| `--autoPublish` | Publishes items that are published in the source | Ignored |
| `--models` without `--models-with-deps` | Syncs those models and their direct content | Limits the run to model definitions only |

Use `sync` unless you have a reason not to. Earlier documentation described `push` as uploading files from an earlier `pull`; in 1.1.0 it reads both instances itself, like `sync`.

## Required settings

| Setting | How to provide it |
| --- | --- |
| Source instance | `--sourceGuid`, or `AGILITY_GUID` in a `.env` file. One GUID per run |
| Target instance | `--targetGuid`, or `AGILITY_TARGET_GUID` in a `.env` file. One GUID per run |
| Locales | `--locales`, or leave it out to use every locale on the source. Without `--locales`, the target must have all of the source's locales or the run stops before writing |
| Sign-in | A browser sign-in, or a Personal Access Token with `--token` or `AGILITY_TOKEN`. The user needs access to both instances |

Passing more than one GUID, separated by commas, stops the run with an error. Earlier versions accepted a list; 1.1.0 handles exactly one source and one target per run.

## Choosing what to sync

| Option | What it syncs |
| --- | --- |
| *(none)* | Everything in the nine elements below |
| `--elements` | A comma-separated subset of `Models,Galleries,Assets,Containers,Content,Templates,Pages,Sitemaps,UrlRedirections` |
| `--models` | The named models and their direct content |
| `--models-with-deps` | The named models plus their dependency tree: content, pages, templates, assets, galleries and containers |
| `--pages` | The named pages (by path, name or page ID), all their child pages, and the templates, content, models, containers, assets and galleries they need. Parent pages are not synced and must already exist on the target |
| `--containers` | The named containers (by reference name, title or container ID), the content they link to and the containers holding it, the models behind all of it, and the assets and galleries it uses. No pages, templates or URL redirections |

`--pages` can't be combined with `--containers`, `--models` or `--models-with-deps`, and `--containers` can't be combined with `--models` or `--models-with-deps`. The run stops with an error if you try. With `--pages` or `--containers`, the CLI prints the resolved scope before it writes anything.

> [!NOTE]
> On Git Bash for Windows, a leading slash in `--pages="/my-page"` is rewritten into a Windows path. Leave the slash off (`--pages="my-page"`) or set `MSYS_NO_PATHCONV=1`.

## Safety options

| Option | Default | What it does |
| --- | --- | --- |
| `--preflight` | `false` | Runs the source pull, target pull and change detection, prints the creates, updates, skips and conflicts a real run would make, and writes nothing to the target or the mapping files. Exits `1` if it finds conflicts |
| `--overwrite` | `false` | When an item changed on both the source and the target since the last sync, the run skips it by default. With `--overwrite`, the source version replaces it. Also recreates a mapped target item that was deleted or unpublished |
| `--autoPublish` | off | `sync` only. After the sync, publishes on the target the items that are published in the source. `content`, `pages` or `both`; the flag with no value means `both`. Ignored with `--preflight` |
| `--fullPull` | `false` | Ignores stored content sync tokens and re-pulls all content and pages first |

A sync never deletes anything on the target.

## JSON summary

`--jsonSummary=<path>` writes a machine-readable record of the run, for CI checks and test harnesses. Parent folders are created; if the file can't be written, the run warns and carries on.

The file is written for a successful run, a failed run, a crash, and a run that stopped before it started (for example a failed sign-in). It includes:

| Field | What it holds |
| --- | --- |
| `schemaVersion` | `1` in 1.1.0 |
| `command` | `sync` or `push` |
| `success`, `exitCode` | The run's own verdict and the exit code it ended with |
| `source`, `target`, `options` | What was run, including `preflight`, `overwrite`, `autoPublish`, `elements`, `locales` and `channel` |
| `phases` | One entry per step (galleries, assets, models, containers, content, templates, pages, URL redirections), with `successful`, `failed` and `skipped` counts and a `status` of `success`, `error` or `notRun`. Content and pages appear once per locale |
| `totals` | `successful`, `failed` and `skipped` across all phases |
| `failures`, `warnings`, `operationErrors` | Item failures, non-blocking warnings, and whole-step failures. A run that stopped before starting has an empty `phases` list and the reason in `operationErrors` |
| `autoPublish` | Publish `errors` (blocking) and `warnings` (non-blocking) |
| `preflight` | With `--preflight`: `totals` and per-phase counts of `create`, `update`, `skip` and `conflict`, `hasConflicts`, and every planned action. Otherwise `null` |
| `run` | `cliVersion`, start and finish times, duration and log file paths. These change on every run, so drop `run` when you compare summaries |

```bash
agility sync --sourceGuid="$SOURCE" --targetGuid="$TARGET" \
  --preflight --headless --jsonSummary=reports/preflight.json

jq '.preflight.totals' reports/preflight.json
```

## Examples

```bash
# Everything, every locale
agility sync --sourceGuid="abc123-u" --targetGuid="def456-u"

# One locale (the target only needs this locale)
agility sync --sourceGuid="abc123-u" --targetGuid="def456-u" --locales="en-us"

# See what would happen, write nothing
agility sync --sourceGuid="abc123-u" --targetGuid="def456-u" --preflight

# Two models and everything they depend on
agility sync --sourceGuid="abc123-u" --targetGuid="def456-u" --models-with-deps="BlogPost,BlogCategory"

# One page structure and its children
agility sync --sourceGuid="abc123-u" --targetGuid="def456-u" --pages="/products"

# One container, leaving other containers on the same model alone
agility sync --sourceGuid="abc123-u" --targetGuid="def456-u" --containers="HomeLinks"

# Let the source win where both sides changed, then publish what is published in the source
agility sync --sourceGuid="abc123-u" --targetGuid="def456-u" --overwrite --autoPublish
```

A CI pattern that gates the real run on a clean preflight:

```bash
set -e
npx agility sync --sourceGuid="$SOURCE" --targetGuid="$TARGET" --headless --preflight \
  --jsonSummary=reports/preflight.json
npx agility sync --sourceGuid="$SOURCE" --targetGuid="$TARGET" --headless \
  --jsonSummary=reports/sync.json
```

If the preflight finds conflicts it exits `1`, so with `set -e` the real sync never runs.

## Exit behavior

Exits `1` when sign-in fails, when the API keys for either instance can't be retrieved, when a precondition fails (such as a missing locale on the target), when the run reports failures or crashes, and when `--preflight` finds conflicts. Otherwise it exits `0`.

## Before you run it

- Keep `agility-files/mappings/` between runs, for example in Git. Without it, the next sync creates duplicates on the target.
- Don't run two syncs against the same source and target at the same time. Both rewrite the same mapping files.
- After syncing A to B, let B finish publishing before you use B as the source for another sync.

## Related

- [reverse-sync](/docs/developers/cli-reverse-sync): bring the target's changes back to the source
- [workflows](/docs/developers/cli-workflows): publish or approve synced items afterwards
- [CLI CI/CD Integration Guide](/docs/developers/cli-ci-cd-integration-guide): pipeline examples