Home

icloudpd-rs Documentation

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

Getting Started

# Homebrew (macOS & Linux)
brew tap rhoopr/icloudpd-rs
brew install icloudpd-rs

# Or Docker
docker pull ghcr.io/rhoopr/icloudpd-rs:latest

# Then run
icloudpd-rs --username my@email.address --directory /photos

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

Commands

icloudpd-rs uses subcommands for different operations. Running without a subcommand defaults to sync.

Command	Description
sync	Download photos from iCloud (default)
status	Show sync status and database summary
retry-failed	Reset failed downloads to pending and re-sync
reset-state	Delete the state database and start fresh
import-existing	Import existing local files into the state database
verify	Verify downloaded files exist and optionally check checksums
submit-code	Submit a 2FA code non-interactively (Docker / headless)

# These are equivalent
icloudpd-rs --username my@email.address --directory /photos
icloudpd-rs sync --username my@email.address --directory /photos

# Check sync status
icloudpd-rs status --username my@email.address

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

# Retry failed downloads
icloudpd-rs retry-failed --username my@email.address --directory /photos

# Verify files exist and checksums match
icloudpd-rs 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
--auth-only	Authenticate without downloading
--domain	iCloud region (com or cn)
--cookie-directory	Session storage path
--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
--list-libraries	List available 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

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