This Bash function icloudownload forces iCloud files or folders to download locally on macOS by reading the first byte of each file, which triggers iCloud sync. It supports both single files and entire directories, displaying progress and file size during the process.

icloudownload.sh

function icloudownload() {
  if ! command -v find >/dev/null; then
    echo "❌ 'find' is not installed. Please install it first."
    return 1
  fi

  if [[ -z "$1" ]]; then
    echo "📂 Usage: icloudownload /path/to/icloud/file_or_folder"
    return 1
  fi

  local target="$1"

  if [[ -f "$target" ]]; then
    local size=$(stat -f%z "$target")
    echo -ne "📄 [1/1] Processing: $target (${size} bytes) \r"
    head -c 1 "$target" > /dev/null
    echo -e "✅ Done: $target (${size} bytes)                    "
  elif [[ -d "$target" ]]; then
    # 正確抓取檔案名，支援空白路徑
    local IFS=$'\n'
    local files=($(find "$target" -type f))
    local total=${#files[@]}
    local count=0

    for file in "${files[@]}"; do
      ((count++))
      local size=$(stat -f%z "$file")
      echo -ne "📄 [$count/$total] Processing: $file (${size} bytes) \r"
      head -c 1 "$file" > /dev/null
    done

    echo -e "\n✅ Folder download complete: $target ($total files)"
  else
    echo "❌ '$target' is not a valid file or folder."
    return 1
  fi
}

Usage

# Download a single iCloud file
icloudownload ~/Documents/file.txt

# Download all iCloud files in a folder
icloudownload ~/Documents/ProjectFolder