Synchronization
The Synchronization commands help you manage file states between your local development environment and remote ZeyOS instances.
Available Commands
| Command | Description | Usage |
|---|---|---|
compare | Compare local and remote state | zeysdk compare [ASSET_PATH...] [options] |
pull | Get latest from instance | zeysdk pull [ASSET_PATH...] [options] |
push | Upload local changes | zeysdk push [ASSET_PATH...] [options] |
sync | Synchronize local and remote state | zeysdk sync [ASSET_PATH...] [options] |
watch | Watch for changes | zeysdk watch [options] |
rollout | Push the application to linked instances | zeysdk rollout [INSTANCE_ID...] [options] |
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 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.