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. NextCloud, Immich, Ente, and Google Takeout next.

---

[!CAUTION] kei is pre-release software under active development, and minor versions may contain breaking changes. We follow a deprecate-then-remove practice, but always check CHANGELOG when updating.

[!IMPORTANT] v0.13 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.

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}

---

Install

brew install rhoopr/kei/kei             # Homebrew
docker pull ghcr.io/rhoopr/kei:latest   # Docker
:latest follows tagged releases. Use :main to track main HEAD for unreleased builds.

Pre-built binaries for macOS, Linux, and Windows are on the Releases page. For Docker Compose, building from source, FreeBSD, and other install paths, see the Install wiki page.

[!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.

---

Quick start

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.

[!TIP] Coming from icloudpd? The Migration Guide shows how to kei sync without re-downloading.

---

Docs

Everything lives on the wiki: full CLI reference, filtering and folder templates, watch mode, Docker Compose, credentials, troubleshooting, and more.

• Commands - sync, login, list, password, config, reset, status, verify, import-existing
• Configuration - TOML file, env vars, precedence
• Docker - Compose files and headless 2FA
• Synology - Container Manager setup, PUID/PGID, Synology Photos integration
• Credentials - keyring, encrypted file, password files and commands
• Changelog
• How iCloud's Incremental Sync Works - deep dive on CloudKit syncTokens

---

Contributing

Contributions welcome. Open an issue first if you're planning something big.

just gate    # pre-push gate: fmt, clippy, tests, doc, audit, typos
just --list  # see every recipe

See CONTRIBUTING.md and tests/README.md for the test catalog.

License

MIT - see LICENSE

Acknowledgments

The iCloud adapter builds on years of reverse-engineering by the icloud-photos-downloader project (kei was originally published as icloudpd-rs before broadening to a multi-provider sync engine). Thanks to the original maintainers for their work, which made the iCloud side of kei possible.