Docker-iCloudPD Command Line Options: Complete Guide to --Initialise, --Convert-All-HEICs, and More

Run docker exec -it <container-name> sync-icloud.sh <option> to execute maintenance commands like --Initialise for authentication setup or --Convert-All-HEICs for HEIC-to-JPEG conversion.

Docker-iCloudPD provides powerful command line options that allow you to manage authentication, convert image formats, and perform library maintenance without recreating the container. These commands are exposed through the sync-icloud.sh entry-point script and can be invoked on a running container using standard Docker exec commands. Understanding these docker-icloudpd command line options is essential for managing your iCloud Photo Library backups effectively.

How to Invoke Command Line Options

All docker-icloudpd command line options are executed through the sync-icloud.sh script inside a running container. The standard syntax requires knowing your container name and the specific flag you want to run.

docker exec -it <container-name> sync-icloud.sh <option>

For example, if your container is named icloudpd, you would initialise authentication with:

docker exec -it icloudpd sync-icloud.sh --Initialise

Authentication and Setup Options

--Initialise

The --Initialise option (also accepts --Initialize or --init) performs the initial setup required for first-run or after changing your Apple ID password. According to the source code in sync-icloud.sh, this action triggers the initialise_container function, which adds your iCloud password to the system keyring and creates a fresh two-factor authentication cookie.

docker exec -it icloudpd sync-icloud.sh --Initialise

This is mandatory the first time you run the container or whenever you change your Apple ID credentials.

--Remove-Keyring

Use --Remove-Keyring when you need to force re-authentication without recreating the container. This flag triggers the delete_password action, which removes the keyring file located at /config/python_keyring/keyring_pass.cfg.

docker exec -it icloudpd sync-icloud.sh --Remove-Keyring

After running this command, you must run --Initialise again to store new credentials.

HEIC and JPEG Management Options

--Convert-All-HEICs

The --Convert-All-HEICs flag scans your download directory for HEIC files that lack matching JPEG counterparts and creates the missing JPEGs. This is implemented in the convert_all_heic_files function and is particularly useful for libraries downloaded before JPEG conversion was enabled.

docker exec -it icloudpd sync-icloud.sh --Convert-All-HEICs

--Force-Convert-All-HEICs

Unlike the standard convert option, --Force-Convert-All-HEICs overwrites existing JPEG files. The implementation includes a built-in 2-minute delay to allow cancellation if invoked accidentally. This triggers the force_convert_all_heic_files function.

docker exec -it icloudpd sync-icloud.sh --Force-Convert-All-HEICs

--Force-Convert-All-mnt-HEICs

This variant operates exclusively on files under the /mnt sub-directory, making it ideal when you bind-mount a host folder into /mnt for external storage. It uses the same force_convert_all_heic_files logic but with a path constraint.

docker exec -it icloudpd sync-icloud.sh --Force-Convert-All-mnt-HEICs

--Remove-All-JPGs

The --Remove-All-JPGs option cleans up your library by deleting every JPEG that has a corresponding HEIC file. This triggers the remove_all_jpeg_files function and is useful when you no longer need JPEG copies to save space.

docker exec -it icloudpd sync-icloud.sh --Remove-All-JPGs

--Correct-JPEG-Time-Stamps

This flag fixes timestamp mismatches where JPEG files do not match the modification times of their associated HEIC source files. The implementation corrects an issue from early releases where timestamps were not properly synchronized during conversion.

docker exec -it icloudpd sync-icloud.sh --Correct-JPEG-Time-Stamps

Library and Upload Options

--Upload-Library-To-Nextcloud

The --Upload-Library-To-Nextcloud command recursively uploads your entire iCloud download tree to a configured Nextcloud instance. This triggers the nextcloud_upload_library function and requires Nextcloud credentials to be configured in your environment variables.

docker exec -it icloudpd sync-icloud.sh --Upload-Library-To-Nextcloud

--Sideways-Copy-All-Videos

This option copies or moves all video files from the main download folder to the location specified by the video_path configuration. The behavior is controlled by the sideways_copy_all_videos_mode setting, which accepts either copy or move as values.

docker exec -it icloudpd sync-icloud.sh --Sideways-Copy-All-Videos

--List-Albums

Use --List-Albums to print the names of all albums available in your iCloud account. This output helps you configure the photo_album environment variable to download specific albums rather than your entire library.

docker exec -it icloudpd sync-icloud.sh --List-Albums

--List-Libraries

The --List-Libraries flag displays all available iCloud photo libraries, including shared libraries. This is essential when you need to specify a particular library for download using configuration options.

docker exec -it icloudpd sync-icloud.sh --List-Libraries

Debugging Options

--Enable-Debugging

This option activates debug logging by setting debug_logging=true in the icloudpd.conf configuration file. The change takes effect immediately without requiring a container restart, triggering the enable_debugging function.

docker exec -it icloudpd sync-icloud.sh --Enable-Debugging

--Disable-Debugging

Conversely, --Disable-Debugging disables debug logging by setting debug_logging=false in the configuration file.

docker exec -it icloudpd sync-icloud.sh --Disable-Debugging

Implementation Details in sync-icloud.sh

The flag-to-action mapping is implemented in sync-icloud.sh around line 2559 using a Bash case statement. When you pass a command line option, the script translates it into an internal action name:

case "${parameter}" in
    "--initialise"|"--initialize"|"--init")          action="initialise_container" ;;
    "--remove-keyring")                               action="delete_password" ;;
    "--convert-all-heics")                            action="convert_all_heics" ;;
    "--remove-all-jpgs")                              action="remove_all_jpgs" ;;
    "--force-convert-all-heics")                      action="force_convert_all_heics" ;;
    "--force-convert-all-mnt-heics")                  action="force_convert_all_mnt_heics" ;;
    "--correct-jpeg-time-stamps")                     action="correct_jpeg_time_stamps" ;;
    "--enable-debugging")                             action="enable_debugging" ;;
    "--disable-debugging")                            action="disable_debugging" ;;
    "--upload-library-to-nextcloud")                  action="nextcloud_upload_library" ;;
    "--sideways-copy-all-videos")                     action="sideways_copy_all_videos" ;;
    "--list-albums")                                 action="list_albums" ;;
    "--list-libraries")                              action="list_libraries" ;;
    *)                                                action="" ;;
esac

Each action corresponds to a specific function defined later in sync-icloud.sh, such as convert_all_heic_files, force_convert_all_heic_files, and remove_all_jpeg_files, ensuring modular and maintainable code structure.

Summary

• Authentication: Use --Initialise for first-time setup and --Remove-Keyring to reset credentials stored in /config/python_keyring/keyring_pass.cfg.
• HEIC Conversion: --Convert-All-HEICs creates missing JPEGs, while --Force-Convert-All-HEICs overwrites existing ones with a safety delay.
• Library Maintenance: --Remove-All-JPGs cleans up redundant JPEGs and --Correct-JPEG-Time-Stamps fixes metadata synchronization issues.
• Integration: --Upload-Library-To-Nextcloud and --Sideways-Copy-All-Videos handle third-party storage and video organization.
• Discovery: --List-Albums and --List-Libraries help identify available content for targeted downloads.
• Debugging: Toggle verbose logging instantly with --Enable-Debugging and --Disable-Debugging without restarting the container.

Frequently Asked Questions

How do I run docker-icloudpd command line options?

Execute any option using Docker's exec command: docker exec -it <container-name> sync-icloud.sh <option>. Replace <container-name> with your actual container name and <option> with flags like --Initialise or --Convert-All-HEICs. All commands run against the live container without requiring a restart.

What is the difference between --Convert-All-HEICs and --Force-Convert-All-HEICs?

--Convert-All-HEICs only creates JPEG files for HEIC images that don't already have a matching JPEG, while --Force-Convert-All-HEICs overwrites all existing JPEGs regardless of whether they exist. The force variant includes a mandatory 2-minute delay to prevent accidental data loss.

When should I use the --Initialise flag?

Use --Initialise during your first container setup or immediately after changing your Apple ID password. This command stores your iCloud credentials in the system keyring and generates the two-factor authentication cookie required for API access. Without running this initialization step, the container cannot authenticate with Apple's servers.

How do I list available albums or libraries?

Run docker exec -it <container-name> sync-icloud.sh --List-Albums to see all album names or --List-Libraries to view all available photo libraries including shared ones. Use the output from these commands to populate the photo_album configuration variable for targeted downloads instead of syncing your entire photo library.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}