https://github.com/rhoopr/kei
Photo sync engine. Parallel downloads, incremental sync, state tracking, and unattended Docker operation, all in a single binary.
https://github.com/rhoopr/kei
apple backup cli docker icloud icloud-photos photo-backup rust selfhosted
Last synced: about 2 months ago
JSON representation
Photo sync engine. Parallel downloads, incremental sync, state tracking, and unattended Docker operation, all in a single binary.
- Host: GitHub
- URL: https://github.com/rhoopr/kei
- Owner: rhoopr
- License: mit
- Created: 2026-02-01T01:59:53.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-04-25T22:02:37.000Z (about 2 months ago)
- Last Synced: 2026-04-25T22:25:26.383Z (about 2 months ago)
- Topics: apple, backup, cli, docker, icloud, icloud-photos, photo-backup, rust, selfhosted
- Language: Rust
- Homepage:
- Size: 2.66 MB
- Stars: 69
- Watchers: 1
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Audit: audit.toml
- Security: SECURITY.md
Awesome Lists containing this project
README
kei: media sync engine
Sync your cloud photos and videos to local storage. Fast, resumable, runs unattended.
- Parallel downloads with incremental sync (seconds on large libraries after the first run)
- Resumable transfers verified by size and content hash
- Watch mode, systemd integration, headless 2FA, Docker-ready
- iCloud Photos supported today. Google Takeout and Immich next.
---
> [!IMPORTANT]
> v0.13 (next release) reshapes selection and folder-structure flags. `--exclude-album NAME` becomes `--album '!NAME'`. `--library` accepts multiple values. `kei sync` with no flags now runs per-album passes plus an unfiled pass. Legacy `{album}` in `--folder-structure` auto-migrates with a warning until v0.20. Full migration guide: [docs/v0.13-migration.md](docs/v0.13-migration.md).
>
> | Flag | Default |
> |---|---|
> | `--album` | `all` |
> | `--smart-folder` | `none` |
> | `--library` | `primary` |
> | `--unfiled` | `true` |
> | `--folder-structure` | `%Y/%m/%d` |
> | `--folder-structure-albums` | `{album}` |
> | `--folder-structure-smart-folders` | `{smart-folder}` |
> [!TIP]
> Coming from `icloudpd`? The [Migration Guide](docs/migration-from-python.md) shows how to `kei sync` without re-downloading.
---
## Install
```sh
brew install rhoopr/kei/kei # Homebrew
docker pull ghcr.io/rhoopr/kei:latest # Docker
```
Pre-built binaries for macOS, Linux, and Windows are on the [Releases page](https://github.com/rhoopr/kei/releases). For Docker Compose, building from source, FreeBSD, and other install paths, see the [Install wiki page](https://github.com/rhoopr/kei/wiki/Install).
> [!IMPORTANT]
> kei can't access your photos if Advanced Data Protection is on. Turn ADP off and enable "Access iCloud Data on the Web" in your Apple ID settings. Details: [Authentication wiki](https://github.com/rhoopr/kei/wiki/Authentication#advanced-data-protection-adp).
---
## Quick start
```sh
kei sync -u you@example.com -d ~/Photos/iCloud --save-password
```
You'll be prompted for your password, then asked to approve 2FA on a trusted device. Downloads start right after. After the first run, just `kei sync` - username, directory, and password are all remembered.
For a guided walkthrough, run `kei config setup` instead.
---
## Docs
Everything lives on the [wiki](https://github.com/rhoopr/kei/wiki): full CLI reference, filtering and folder templates, watch mode, Docker Compose, credentials, troubleshooting, and more.
- [Commands](https://github.com/rhoopr/kei/wiki/Home#commands) - `sync`, `login`, `list`, `password`, `config`, `reset`, `status`, `verify`, `import-existing`
- [Configuration](https://github.com/rhoopr/kei/wiki/Configuration) - TOML file, env vars, precedence
- [Docker](https://github.com/rhoopr/kei/wiki/Docker) - Compose files and headless 2FA
- [Credentials](https://github.com/rhoopr/kei/wiki/Credentials) - keyring, encrypted file, password files and commands
- [Changelog](CHANGELOG.md)
- [How iCloud's Incremental Sync Works](https://robhooper.xyz/blog-synctoken) - deep dive on CloudKit syncTokens
---
## Contributing
Contributions welcome. Open an issue first if you're planning something big.
```sh
just gate # pre-push gate: fmt, clippy, tests, doc, audit, typos
just --list # see every recipe
```
See [CONTRIBUTING.md](CONTRIBUTING.md) and [tests/README.md](tests/README.md) for the test catalog.
## License
MIT - see [LICENSE](LICENSE)
## Acknowledgments
kei started as `icloudpd-rs`, a Rust rewrite of [icloud-photos-downloader](https://github.com/icloud-photos-downloader/icloud_photos_downloader). Thanks to the original maintainers for their reverse-engineering work.