Reference

This is a list of all options available for command line interface (CLI) of the icloudpd

--until-found X

Checks assets, from most recently added to the oldest, for their local copies. Downloads if not present locally. Whole process stops once X number of subsequent checks result in a local file matching remote.

This option is a useful optimization for incremental updates: only small portion (X) of the existing local storage will be rechecked for existence, saving on local IO. However, the process will not “fill the gaps” in local storage if any exist (and will not identify them).

Note

Assets are checked by the date they were added to iCloud, not by the date they were taken/created.

--recent X

Checks X most recently added assets for their local copies. Downloads if not present locally.

This option is mostly useful while testing and experimenting with parameters to limit the volume of downloads

Note

Assets are checked by the date they were added to iCloud, not by the date they were taken/created.

--album X

Specifies what Album to download.

When not specified, the whole asset collection is considered.

Note

Only one album can be downloaded by icloudpd

--list-albums

Lists all available albums

--library X

Specifies what Libarary to use.

Default: “Personal Library”.

Note

Only one library can be used by icloudpd

--list-libraries

Lists all libraries available for account

--watch-with-interval X

Runs icloudpd forever, periodically re-checking iCloud for changes (“watch”). Interval is specified in seconds, e.g. 3600 will be 1hr interval.

Too short interval may trigger throttling on Apple side, although no evidence has been reported.

--version

Reports current version and commit hash & date that version was build from.

Note

If --use-os-locale was specified before --version, then date is formatted according to OS locale.

--use-os-locale

Instructs icloudpd to use OS locale. If not specified (and by default), US English is used.

See also

File Naming section discusses affected behavior

--dry-run

If specified, no changes to local storage or iCloud remote storage is made.

Authentication will be performed and remote files will be checked against local storage. Any difference will be reported instead of performing download.

This parameter is useful for experimenting with new parameters

--domain X

Access to Apple servers is blocked from mainland China. As an alternative, iCloud service is available on internal .cn domain, which can be specified for icloudpd to work from mainland China.

Default is “.com”. “.cn” is the only other option available.

--password X

Specifies iCloud password to use for authentication

Note

Supplying credentials through command line parameters is considered not a good practice since they can be logged and/or otherwise exposed. Consider using other password providers.

--directory X

Specifies root folder where folder structure will start and files will be downloaded.

--file-match-policy X

Specifies an algorithm (policy) to match remote to local files.

See also

Discussion on File Naming and Deduplication

--username X

Specifies AppleID (email address) used for authenticating to iCloud.

--auth-only

Performs authentication, persists auth results (tokens/cookies), and exists without processing assets

--cookie-directory X

Customizes folder used for persisting authentication results (cookies/tokens). If not specified, ~/.pyicloud is used.

--size X

Customizes size of the asset to download.

See also

Details on Assets sizes

--force-size

If specified, only requested size will be downloaded. Otherwise, original size will be downloaded instead of missing size.

See also

--size parameter

--live-photo-size X

Customizes size of the live photo assets to download.

--skip-videos

If specified, video assets will not be processed

--skip-live-photos

If specified, live photo assets will not be processed

--auto-delete

If specified, assets deleted in iCloud (actually moved to Recently Deleted album), will also be deleted locally.

See also

Modes of operation

--delete-after-download

If specified, assets downloaded locally will be deleted in iCloud (actually moved to Recently Deleted album). Deprecated, use --keep-icloud-recent-days instead

Note

If remote assets were not downloaded, e.g. because they were already in local storage, they will NOT be deleted in iCloud.

Added in version 1.21.0.

Deprecated since version 1.26.0.

--keep-icloud-recent-days X

Deletes assets in iCloud after they were downloaded or confirmed present locally, except the ones taken within the specified number of days. If set to 0, all photos will be deleted from iCloud.

If any filters are used, e.g. --skip-videos, then assets excluded from processing by filters are not subject to deletion from iCloud. For example, running icloudpd with --skip-videos on a huge iCloud collection of videos will download and delete nothing.

Timestamp when the assets was taken (aka “created date”) as reported by iCloud is used for calculating age of the asset. For example, asset taken in 2000, but added to iCloud in 2024, will be 25 years old in 2025. Same timestamp is used for the folder structure in the current system.

If parameter is not specified, then nothing is deleted from iCloud.

Added in version 1.26.0.

See also

Modes of operation

Folder Structure

--only-print-filenames

If specified, no downloading will occur, but only file paths printed in the output (no other info goes into output either).

See also

--dry-run parameter

--folder-structure X

Specifies sub folder naming scheme.

See also

Details in Folder structure section.

--set-exif-datetime

If specified, EXIF data for the image will be updated with date/time of the assets take/created. Only if EXIF does not exist already in the asset.

--no-progress-bar

If specified, progress bar is suppressed. Valuable when streaming output to file

--keep-unicode-in-filenames

If specified, unicode chars will be preserved in filenames. Otherwise they are removed (default).

--live-photo-mov-filename-policy X

Customizes naming of the video portion of the live photos.

See also

Details in Live Photo section.

--align-raw X

Customizes treating of the RAW+JPEG assets.

See also

Details in RAW+JPEG section.

--password-provider X

Customizes intake of the password for iCloud authentication.

See also

Details in Password providers section.

--mfa-provider X

Customizes intake of the multi-factor authentication (MFA) code for iCloud authentication.

See also

Details in MFA providers section.

--xmp-sidecar

Export additional data as XMP sidecar files (default: don’t export)

--smtp-username X, --smtp-password X, --smtp-host X, --smtp-port X, --smtp-no-tls

Settings for SMTP notification for expired/needed authentication.

--notification-email X, --notification-email-from X

Settings for email notification addressing

--notification-script X

Script to be executed for notification on expired MFA

--skip-created-before

Does not process assets created before specified timestamp. Timestamp is in ISO format, e.g 2025-06-01, or as interval from now, e.g. 5d. If timezone is not specified for ISO format, then local timezone is used.

Added in version 1.28.0.

Note

The date is when the asset was created, not added to the iCloud.

--skip-created-after

Does not process assets created after specified timestamp. Timestamp is in ISO format, e.g 2025-06-01, or as interval from now, e.g. 5d. If timezone is not specified for ISO format, then local timezone is used.

Added in version 1.29.0.

Note

The date is when the asset was created, not added to the iCloud.