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

> Master docker-icloudpd command line options like Initialize and ConvertAllHEICs. Learn to manage iCloud photos and HEIC conversions efficiently.

- Repository: [boredazfcuk/docker-icloudpd](https://github.com/boredazfcuk/docker-icloudpd)
- Tags: api-reference
- Published: 2026-02-26

---

**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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) script inside a running container. The standard syntax requires knowing your container name and the specific flag you want to run.

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

```

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

```bash
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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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.

```bash
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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/python_keyring/keyring_pass.cfg).

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/icloudpd.conf) configuration file. The change takes effect immediately without requiring a container restart, triggering the `enable_debugging` function.

```bash
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.

```bash
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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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:

```bash
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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//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.