-
-
Notifications
You must be signed in to change notification settings - Fork 5
State Tracking
icloudpd-rs uses a SQLite database to track the state of every asset across sync runs.
The state database is stored at {cookie_directory}/{username}.db (default: ~/.icloudpd-rs/{username}.db).
For each iCloud asset:
| Field | Description |
|---|---|
asset_id |
Unique iCloud asset identifier |
status |
pending, downloaded, or failed
|
checksum |
SHA256 checksum from iCloud |
filename |
Original filename |
local_path |
Where the file was downloaded |
download_attempts |
Number of retry attempts |
last_error |
Error message from last failure |
created_at |
Asset creation date in iCloud |
downloaded_at |
When the file was downloaded locally |
For each sync run:
| Field | Description |
|---|---|
started_at |
When the sync began |
completed_at |
When the sync finished (null if interrupted) |
assets_seen |
Total assets enumerated from API |
assets_downloaded |
Successfully downloaded count |
assets_failed |
Failed download count |
interrupted |
Whether the run was interrupted |
On the first run, every asset is enumerated and downloaded. On subsequent runs, assets already marked as downloaded are skipped without any filesystem checks. This makes re-running icloudpd-rs nearly instant for unchanged libraries.
If the database says a file is downloaded but the file is missing from disk, it's automatically re-downloaded. This handles cases where files were accidentally deleted or moved.
Assets that fail to download are marked as failed with their error message. You can:
- View failed assets with
icloudpd-rs status --failed - Retry them with
icloudpd-rs retry-failed
If a sync is interrupted (Ctrl+C, crash, reboot), the next run picks up where it left off. Assets already downloaded are skipped, and only pending/failed assets are attempted.
The state database enables several management commands:
| Command | Description |
|---|---|
status |
Show sync status and database summary |
status --failed |
List failed assets with error messages |
retry-failed |
Reset failed assets to pending and re-sync |
reset-state |
Delete the database and start fresh |
import-existing |
Scan local files and mark matching assets as downloaded |
verify |
Check that downloaded files still exist |
verify --checksums |
Also verify SHA256 checksums |
If you have files from a previous tool (Python icloudpd, manual download, etc.), use import-existing to populate the database:
icloudpd-rs import-existing -u my@email.address -d /photosThis scans the download directory, matches files to iCloud assets by filename and size, and marks them as downloaded. The next sync will skip these files.
To start fresh and re-download everything:
icloudpd-rs reset-state -u my@email.address --yesThis deletes the database file. The next sync will treat all assets as new.
The database uses SQLite with two main tables:
-
assets— One row per iCloud asset -
sync_runs— One row per sync execution
Schema migrations are handled automatically when upgrading icloudpd-rs versions.