Home

kei Documentation

Coming from Python icloudpd? See the Migration Guide for flag mapping and how to import existing files.

Getting Started

# Homebrew (macOS & Linux)
brew install rhoopr/kei/kei

# Or Docker
docker pull ghcr.io/rhoopr/kei:latest

# Then run
kei sync -u my@email.address -d /photos

Use --dry-run to preview what would be downloaded. Use kei login to verify credentials without starting a download.

Note: kei requires ADP to be off and "Access iCloud Data on the Web" to be on. See Authentication for details.

Commands

kei uses subcommands for different operations. Running without a subcommand defaults to sync.

Command	Description
sync	Download photos from iCloud (default)
login	Authenticate and complete 2FA (get-code, submit-code)
list	List albums (albums) or libraries (libraries)
password	Manage stored credentials (set, clear, backend)
config	Show resolved config (show) or run the setup wizard (setup)
reset	Delete state database (state) or clear sync tokens (sync-token)
status	Show sync status and database summary
verify	Verify downloaded files exist and optionally check checksums
import-existing	Import existing local files into the state database

Backward compatibility: The old command names (--auth-only, retry-failed, reset-state, get-code, submit-code, credential, setup, --list-albums, --list-libraries) still work but print a deprecation warning.

# These are equivalent
kei -u my@email.address -d /photos
kei sync -u my@email.address -d /photos

# Check sync status
kei status -u my@email.address

# List failed downloads
kei status -u my@email.address --failed

# Retry failed downloads
kei sync --retry-failed -u my@email.address -d /photos

# Verify files exist and checksums match
kei verify -u my@email.address --checksums

See State Tracking for details on how the database works.

CLI Reference

Global Flags

These apply to all commands:

Flag	Description
-u, --username	Apple ID email
--config	TOML config file path (default: ~/.config/kei/config.toml)
--data-dir	Session, state, and credential storage path
--domain	iCloud region (com or cn)
--log-level	Log verbosity (debug, info, warn, error)

sync

Download photos from iCloud. The default when no subcommand is given.

Key flags: -d, --directory, -a, --album, --size, --threads-num, --watch-with-interval, --dry-run, --retry-failed, --max-download-attempts

See the full sync flag reference.

login

Authenticate with iCloud. Subcommands: get-code, submit-code <code>.

list

List albums or libraries. Subcommands: albums, libraries. Accepts --library to scope the listing.

password

Manage stored credentials. Subcommands: set, clear, backend.

reset

Reset state data. Subcommands: state (delete DB), sync-token (clear sync tokens).

config

Configuration management. Subcommands: show (dump resolved config), setup (interactive wizard).

status

Show sync summary and database stats. Use --failed to list failed assets with errors.

verify

Verify downloaded files exist. Use --checksums for SHA256 content verification.

import-existing

Import existing local files into the state database. Key flags: -d, --directory, --folder-structure, --library.

Features

Topic	Description
State Tracking	SQLite database for sync state and resume
Authentication & 2FA	SRP-6a, trusted device codes, session persistence
Credentials	Password sources, OS keyring, encrypted file store
Download Pipeline	Streaming, resumable, concurrent downloads
Content Validation	Magic byte, Content-Length, and HTML rejection checks
Live Photos	MOV companion file handling
Content Filtering	Media type, date range, album filters
Retry & Resilience	Exponential backoff, checksum verification
Watch Mode	Continuous sync with interval
EXIF Handling	Date tag reading and writing
Folder Structure	Date-based directory organization
Configuration	TOML config file guide
Docker	Container setup and docker-compose