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 --username my@email.address --directory /photos

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

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 without downloading
login get-code	Request a 2FA push notification from Apple
login submit-code	Submit a 2FA code non-interactively (Docker / headless)
list albums	List available albums and exit
list libraries	List available libraries and exit
status	Show sync status and database summary
import-existing	Import existing local files into the state database
verify	Verify downloaded files exist and optionally check checksums
password	Manage stored passwords (set, clear, backend)
config setup	Interactive configuration wizard
config show	Dump resolved config as TOML
reset state	Delete the state database and start fresh
reset sync-token	Clear sync tokens before syncing

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 --username my@email.address --directory /photos
kei sync --username my@email.address --directory /photos

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

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

# Retry failed downloads
kei sync --retry-failed --username my@email.address --directory /photos

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

See State Tracking for details on how the database works.

CLI Reference

Authentication

Flag	Description
-u, --username	Apple ID email
-p, --password	iCloud password
--password-file	Read password from a file
--password-command	Run a command to get the password
--save-password	Persist password to credential store
--auth-only	Authenticate without downloading (deprecated - use kei login)
--domain	iCloud region (com or cn)
--data-dir	Session, state, and credential storage path
--cookie-directory	Session storage path (deprecated - use --data-dir)
--config	TOML config file path

Content Selection

Flag	Description
-a, --album	Album(s) to download
--library	Library to download from (all for every library)
-l, --list-albums	List available albums (deprecated - use kei list albums)
--list-libraries	List available libraries (deprecated - use kei list libraries)
--recent	Download only N most recent photos
--skip-videos	Don't download videos
--skip-photos	Don't download photos
--skip-live-photos	Don't download live photos
--skip-created-before	Skip assets before a date
--skip-created-after	Skip assets after a date

Download Options

Flag	Description
-d, --directory	Local download directory
--size	Image size variant
--force-size	Skip assets without exact size
--align-raw	RAW/JPEG alignment policy
--live-photo-size	Live photo MOV size variant
--live-photo-mov-filename-policy	MOV filename style
--folder-structure	Date-based folder template
--file-match-policy	File deduplication policy
--keep-unicode-in-filenames	Preserve Unicode in filenames
--set-exif-datetime	Write EXIF tags
--threads-num	Concurrent downloads
--max-retries	Retry limit per download
--retry-delay	Initial retry delay
--no-progress-bar	Disable progress bar
--dry-run	Preview without writing files
--only-print-filenames	Print download paths for scripting

Operational

Flag	Description
--watch-with-interval	Continuous sync mode
--notify-systemd	systemd sd_notify integration
--pid-file	Write PID file for service managers
--temp-suffix	Temp file suffix for partial downloads
--notification-script	Run a script on sync events
--no-incremental	Force full library scan
--reset-sync-token	Clear sync tokens before syncing (deprecated - use kei reset sync-token)
--log-level	Log verbosity

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
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