iCloud Photos Sync
Overview
This project provides a one-way sync engine for the iCloud Photos Library. The intention behind this project is to provide an easy way, to backup the full iCloud Photos Library to the native filesystem.
Currently, this can only be achieved, by having a Mac continuously run the Photos.app (with Keep originals enabled). With this method, the files cannot be easily viewed without the Photos.app.
This CLI Application offers the following high level functionality:
Continuously sync your complete remote iCloud Photos Library to your local file system efficiently
- iCloud Shared Photo Library support
- Support of MFA authentication through trusted devices, SMS and voice authentication - [Security Key Support pending, please help out if you have this use case](#207)!
- Enable autonomous operation, by caching of MFA trust token
- Support of large libraries, through efficient diffing algorithm instead of full library pull
- Full iCloud Photos Library backup with all important files in their original state and edits - [Live Photos support pending](#121)
Efficient handling of local state
- Each asset is only downloaded once and linked to its respective folders
- No need track local state in database, since state is completely reflected in filesystem (through naming & linking)
Archiving of folders
- All assets currently in the album will be persisted in the respective folder on the machine running icloud-photos-sync
- Future syncs will ignore the folder (so those assets will not be changed/deleted)
- If the remote album is moved, the archived folder will be moved to the same location
- If the remote album is deleted, the archived folder will be put into a 'lost+found' type of folder
- Optionally all photos from the archived folder can be deleted from the iCloud Photos Library, unless they are *Favorites* (reducing cloud storage needs)
Single purpose iCloud Photos application
- No reliance on full fledged third-party libraries that provide access to iCloud
- No configuration needed for continuous full backup
- Quicker support of use-case specific needs
Documentation
A Get Started Guide can be found on GH Pages. Additional documentation and further resources - including my personal use case / workflow - are published there as well.
Limitations
As this application is using an undocumented public API, there are a couple of known limitations:
- iCloud Shared Photo Library:
While this app is syncing all assets from the Shared Photo Library, unfortunately the API does not provide the location of shared assets within the user's folder hierarchy (when navigating to a folder on the WebUI while having Shared Photo Library enabled will yield an error). Until this functionality is available, Shared Photo Library assets will only be present in the
_Shared-Photosfolder and therefore cannot be archived. - Advanced Data Protection: In order to use this app with an account that is secured through Advanced Data Protection, please make sure access through the iCloud WebUI is enabled. This is a minimum requirement since this tool is re-using those APIs - I'm still waiting on confirmation that this will enable functionality, please report your experience!
- FileType Support:
The support of file types needs to be hardcoded by this application, since a full list is not available or retrievable. If you come across an
Unknown filetype descriptorerror, please report it, in order for the file type to be added to the application.
OS Support
Contributing & Feedback
Please re-try the sync a couple of times before reporting an issue. The application will reload from the filesystem and therefore recover from "corrupted" states. After that, check known issues before opening an issue. Always enable crash and error reporting, so this crash and all required technical details are recorded and reported.
Pull requests are always welcomed! Please open them against the dev branch for quick consideration. I tried to make this codebase as maintainable and automated as possible, in order to make future releases and contributions quick and easy, while ensuring functionality. This includes unit, API & E2E tests.