Recover Sync State

The recover command lists, restores, or deletes the rotating backups of .zeysdk/sync.json created by pull, push, and sync operations.

Bash

zeysdk recover [options]

Options

Option	Description
--list	List available backups, their indexes, paths, and relative ages
--backup <index>	Restore a backup index; 0 is the newest and is the default
--clean	Delete all rotating sync.json backups
-f, --force	Skip the restore or cleanup confirmation

Backup Files

Before applying changes in a non-dry-run pull, push, or sync, the CLI rotates up to three sync-state backups:

Text

.zeysdk/sync.json.backup      # index 0, newest
.zeysdk/sync.json.backup.1    # index 1
.zeysdk/sync.json.backup.2    # index 2, oldest retained

The newest backup is retained after a successful operation and is also used for the automatic restore attempted when that operation reports a failure.

Operations

1. List backups

   Bash

   zeysdk recover --list

   Listing does not change sync.json or the backups.

2. Restore a backup

   Bash

   zeysdk recover
   zeysdk recover --backup 1
   zeysdk recover --backup 0 --force

   Restore overwrites the current .zeysdk/sync.json. Without --force, the command asks for confirmation and defaults to proceeding.

3. Delete all backups

   Bash

   zeysdk recover --clean
   zeysdk recover --clean --force

   Without --force, cleanup asks for confirmation and defaults to cancellation.

Use one operation mode at a time. If options are combined, --list takes precedence over --clean and restore, while --clean takes precedence over restore.

Locking

Every recover mode, including --list, acquires .zeysdk/.sync.lock and releases it from a finally path. This prevents sync.json backup files from being listed, restored, or deleted while another synchronization command is rotating or updating them.

Recover does not expose --break-lock. Wait for the current operation to finish and retry. A stale lock is reclaimed automatically.

Important Recovery Scope

Recover restores only .zeysdk/sync.json. It does not restore:

• project source or asset files;
• zeyos.app.json manifest changes;
• remote server state or a server patch that already succeeded;
• rollout's timestamped ZIP archives under .zeysdk/backups/.

After recovering an older sync baseline, run zeysdk compare before the next modifying command. The recovered baseline may intentionally differ from both current local files and current server state.

Error Handling

Error	Description	Resolution
No backups	No rotating sync-state backup exists	Run --list; recover files through version control or another backup if necessary
Invalid index	The complete value is not a non-negative decimal integer, or the index is unavailable	Use an index reported by zeysdk recover --list
Lock error	Another synchronization operation owns the project lock	Wait for it to finish and retry
Restore error	The selected backup cannot be copied over sync.json	Check file permissions and available disk space

Best Practices

• Run zeysdk recover --list before restoring.
• Preserve or commit current work before replacing the sync baseline.
• Use zeysdk compare immediately after recovery.
• Treat rollout ZIP archives as manual snapshots, not as inputs to zeysdk recover.