icloud-resolver 0.1.0

Add your description here

iCloud Resolver

A fast and lightweight Python library and CLI tool to securely resolve and download files from iCloud Drive public links.

How it works

When you share a public iCloud Drive link (e.g., https://www.icloud.com/iclouddrive/...), it is not a direct file download link. Instead, it leads to Apple's web application.

This tool bypasses the browser by interacting directly with Apple's public CloudKit API. It parses the unique identifier from the link, queries the iCloud database, and safely retrieves the original filename along with the highly-secure, direct downloadURL. Finally, it streams the file directly to your disk with a progress bar.

(Note: iCloud Drive folders are currently not supported because downloading them requires user authentication and dynamic zip archiving).

---

Command Line Interface (CLI)

You can run this tool instantly from your terminal using zero-install execution tools like uvx or pipx:

# Using uvx
uvx icloud-resolver "https://www.icloud.com/iclouddrive/0afGK6zDBog_0drwp6YZoDLIg#Patches"

# Using pipx
pipx run icloud-resolver "https://www.icloud.com/iclouddrive/0afGK6zDBog_0drwp6YZoDLIg#Patches"

If you install the package globally (e.g. uv tool install .), it exposes two aliases that you can use interchangeably: icloud-resolver and the shorter icr.

CLI Options

• Download to the current directory:

  icr "https://www.icloud.com/iclouddrive/..."
  

• Specify an output directory or custom file name:

  icr -o ./my_downloads "https://www.icloud.com/iclouddrive/..."
  icr -o custom_file.zip "https://www.icloud.com/iclouddrive/..."
  

• Only resolve the URL (print the direct download link without downloading):

  icr -r "https://www.icloud.com/iclouddrive/..."
  

---

Programmatic Usage

You can also import icloud-resolver directly into your own Python scripts. The library features robust custom exceptions for smooth programmatic error handling.

example.py

from icloud_resolver import resolve_icloud_link, download_file
from icloud_resolver.exceptions import (
    ICloudResolverError, 
    FolderNotSupportedError
)

url = "https://www.icloud.com/iclouddrive/0afGK6zDBog_0drwp6YZoDLIg#Patches"

# Example 1: Resolving the link without downloading
try:
    direct_url, filename = resolve_icloud_link(url)
    print(f"Original Name: {filename}")
    print(f"Direct Link: {direct_url}")
except FolderNotSupportedError:
    print("Oops! This link points to a folder, which is unsupported.")
except ICloudResolverError as e:
    print(f"Something went wrong: {e}")

# Example 2: Downloading the file directly
try:
    # Set target_path to a directory to auto-use the original filename, 
    # or set it to a full path to use a custom filename.
    saved_path = download_file(url, target_path=".")
    print(f"File successfully downloaded to: {saved_path}")
except ICloudResolverError as e:
    print(f"Download failed: {e}")