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

Usage

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

From agility reverse-sync --help:

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. In the JSON summary, a reverse sync is recorded with command set to sync.

Examples

# 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, plus exit 1 when the GUIDs are missing or identical.

Related

• sync and push
• Agility CLI: mappings and conflicts