# agility reverse-sync

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

`agility reverse-sync` copies changes made on the **target** of an earlier sync back into its **source**, reusing the mapping files that sync created. Items that were synced forward are updated in the source instead of duplicated.

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

## Usage

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

From `agility reverse-sync --help`:

```text
agility reverse-sync

Sync the target instance back to the source instance, reusing (and updating) the
mapping files from the original sync. Pass the same --sourceGuid/--targetGuid as
the forward sync.
```

## Pass the same GUIDs as the forward sync

Don't swap them. The CLI reverses the direction itself:

| Option | Meaning in reverse-sync (from `--help`) |
| --- | --- |
| `--sourceGuid` | The ORIGINAL source instance GUID from the forward sync (this run writes INTO it). Required; falls back to AGILITY_GUID from .env. |
| `--targetGuid` | The ORIGINAL target instance GUID from the forward sync (this run reads FROM it). Required; falls back to AGILITY_TARGET_GUID from .env. |

If either GUID is missing, or both are the same, the command stops with an error and exits `1`.

## How it works

- It reads the mapping files in `agility-files/mappings/{sourceGuid}-{targetGuid}/`, in their original orientation. No reversed folder is created.
- Items synced forward are matched through those mappings and **updated** in the source.
- Items that exist only on the target (created after the forward sync) are **created** in the source, and a mapping record is added, so a later forward sync treats them as already synced.
- Before its first write, it copies the mapping files to `agility-files/mappings-backups/{sourceGuid}-{targetGuid}/{timestamp}/`. With `--preflight`, nothing is written and no backup is taken. If the backup fails, the run stops before writing.
- It never deletes anything. Items that exist only in the source are left alone.

All other sync options work the same way, including `--locales`, `--elements`, `--models`, `--models-with-deps`, `--pages`, `--containers`, `--preflight`, `--overwrite`, `--autoPublish` and `--jsonSummary`. See [sync and push](/docs/developers/cli-sync). In the JSON summary, a reverse sync is recorded with `command` set to `sync`.

## Examples

```bash
# The forward sync, A to B
agility sync --sourceGuid="A-u" --targetGuid="B-u" --locales="en-us"

# Later: preview what bringing B's edits back into A would do
agility reverse-sync --sourceGuid="A-u" --targetGuid="B-u" --locales="en-us" --preflight

# Then run it
agility reverse-sync --sourceGuid="A-u" --targetGuid="B-u" --locales="en-us"
```

## Things to watch

- Run it from the folder that holds the forward sync's `agility-files/mappings/`. Without those mappings, nothing can be matched and items are created as new.
- Don't run a forward `sync` and a `reverse-sync` for the same pair at the same time. Both rewrite the same mapping files.
- Run with `--preflight` first and read the report. A reverse sync writes into the instance you originally treated as the source of truth.

## Exit behavior

The same as [sync](/docs/developers/cli-sync#exit-behavior), plus exit `1` when the GUIDs are missing or identical.

## Related

- [sync and push](/docs/developers/cli-sync)
- [Agility CLI](/docs/developers/cli): mappings and conflicts