---
title: "Synchronization"
description: "Documentation for Synchronization in ZeyOS SDK CLI"
canonical_url: "https://www.zeyos.com/sdk/synchronization"
markdown_url: "https://www.zeyos.com/ai/guide/sdk/synchronization.md"
section: "sdk"
authority: "guide"
language: "en"
source_repository: "zeyos/sdk-v2"
source_path: "docs/Synchronization/index.md"
source_revision: "a99897af74253b4dc5af6fecb9301cea0ae18e27"
---

# Synchronization

The Synchronization commands help you manage file states between your local development environment and remote ZeyOS instances.

Available Commands
------------------

| Command | Description | Usage |
|---------|-------------|-------|
| [`compare`](https://www.zeyos.com/sdk/synchronization/zeysdk-compare) | Compare local and remote state | `zeysdk compare [ASSET_PATH...] [options]` |
| [`pull`](https://www.zeyos.com/sdk/synchronization/zeysdk-pull) | Get latest from instance | `zeysdk pull [ASSET_PATH...] [options]` |
| [`push`](https://www.zeyos.com/sdk/synchronization/zeysdk-push) | Upload local changes | `zeysdk push [ASSET_PATH...] [options]` |
| [`sync`](https://www.zeyos.com/sdk/synchronization/zeysdk-sync) | Synchronize local and remote state | `zeysdk sync [ASSET_PATH...] [options]` |
| [`watch`](https://www.zeyos.com/sdk/synchronization/zeysdk-watch) | Watch for changes | `zeysdk watch [options]` |
| [`rollout`](https://www.zeyos.com/sdk/application-management/zeysdk-rollout) | Push the application to linked instances | `zeysdk rollout [INSTANCE_ID...] [options]` |
| [`recover`](https://www.zeyos.com/sdk/synchronization/zeysdk-recover) | List, restore, or delete sync-state backups | `zeysdk recover [options]` |

Shared Synchronization Safety
-----------------------------

`pull`, `push`, `sync`, the instance-switching and push phase of `rollout`, and every `recover` operation use the project lock at `.zeysdk/.sync.lock`. The lock is created atomically and contains an owner token, so one operation cannot release a lock owned by another. Locks are released when an operation succeeds, fails, or is cancelled.

If the lock belongs to a running process, wait for that operation to finish. Stale locks are reclaimed automatically. `pull`, `push`, `sync`, `rollout`, `link`, `unlink`, and `use` also expose `--break-lock`, but use it only after confirming that the recorded process is no longer performing work. `link`, `unlink`, and `use` acquire the same lock so the active instance cannot change during synchronization. `compare` does not acquire the lock. `watch` acquires it for each automatic push rather than for the lifetime of the watcher.

Dry Runs
--------

`pull --dry-run`, `push --dry-run`, and `sync --dry-run` scan local state and read server state, then report planned work without applying server mutations or changing project files, the application manifest, or `sync.json`. They also skip creation of a `sync.json` backup. If `--debug-log` is supplied, diagnostic output is still written to `.zeysdk/debug.log`. A sync dry-run may remove an SDK-owned merge temporary file older than one hour from the system temporary directory.

There is no dry-run option for `watch` or `rollout`. `compare` is the read-only preview command.

Backups and Recovery
--------------------

Before a non-dry-run `pull`, `push`, or `sync`, the CLI rotates a small set of `.zeysdk/sync.json.backup*` files. On a reported failure it attempts to restore the newest one. These backups contain only `sync.json`; they do not undo local file changes, manifest changes, or server changes that happened before a later step failed. Use [`recover`](https://www.zeyos.com/sdk/synchronization/zeysdk-recover) to inspect or restore them manually.

Rollout's optional timestamped ZIP under `.zeysdk/backups/` is separate. It contains per-instance project copies populated from server state, is not managed by `recover`, and is not applied automatically as rollback.

Rollout Behavior
----------------

Targets can be supplied explicitly, selected interactively when no IDs are supplied, or discovered with `--all`. Automatic discovery accepts regular files named exactly `sync.<INSTANCE_ID>.json`, removes duplicate IDs, and processes the active instance first when it is included.

`rollout` validates each target's stored credentials, optionally creates the ZIP described above, and pushes targets sequentially while switching linked instances. The originally active instance is restored in a `finally` path, including after a failed push. With `--force`, validation, backup, or push failures are recorded while eligible targets continue; the command still finishes with a non-zero status when any failure was recorded. Rollout has no dry-run mode or automatic server rollback.