icloud-pp-cli

Apple iCloud — CLI 技能

前提条件：安装 CLI

此技能通过 icloud-pp-cli 二进制文件执行操作。**调用此技能中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 通过 Printing Press 安装程序安装。默认情况下，二进制文件安装到 macOS/Linux 上的 $HOME/.local/bin，以及 Windows 上的 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install icloud --cli-only
   

2. 验证：icloud-pp-cli --version
3. 确保报告的安装目录已加入将调用此技能的 Agent/运行时的 $PATH。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接通过 Go 安装的方式（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/icloud/cmd/icloud-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。验证成功前，请勿继续执行技能命令。

安装前检查

请务必先运行 doctor，确认设置无误：

icloud-pp-cli doctor

此命令会验证：macOS、已安装 Photos.app、已找到图库路径、数据库架构有效、可查询资源数量、可读取 chat.db（完全磁盘访问权限）。

如果你的 Photos 图库位于非默认位置：

icloud-pp-cli doctor --library "/Volumes/External/Photos Library.photoslibrary/database/Photos.sqlite"

Messages：需要完全磁盘访问权限

messages 子命令会直接读取 ~/Library/Messages/chat.db，在 macOS 上，调用该二进制文件的终端应用必须拥有完全磁盘访问权限（FDA）。 如果 messages 命令失败并提示“Full Disk Access not granted”，请打开“系统 设置”>“隐私与安全性”>“完全磁盘访问权限”，添加你的终端应用，然后退出并 重新打开终端，再次运行命令。doctor 会自动报告 FDA 状态。

命令参考

photos — 查询和管理你的 Photos 图库。

• icloud-pp-cli photos stats — 快速摘要：资源总数和图库总大小。
• icloud-pp-cli photos storage — 按媒体类型（照片/视频）和年份细分存储空间。
• icloud-pp-cli photos top — 列出所有媒体类型中体积最大的文件。
• icloud-pp-cli photos videos — 按文件大小排序，列出体积最大的视频。
• icloud-pp-cli photos delete <uuid...> — 将资源移至 Photos.app 中的“最近删除”（需要 --confirm）。
• icloud-pp-cli photos download [uuid...] --output <dir> — 将原件从 iCloud 导出到本地文件夹。如果启用了“优化 Mac 储存空间”，Photos.app 会自动从 iCloud 下载内容。
• icloud-pp-cli photos download --sensitive --confirm --output <dir> — 导出 Apple 设备端 ML 标记为包含裸露内容的资源（需要 --confirm）。

messages — 从 ~/Library/Messages/chat.db 读取你的 iMessage 历史记录。需要完全磁盘访问权限。

• icloud-pp-cli messages list-chats — 按最近活动时间排序的聊天列表。标志：--limit、--since、--include-empty。
• icloud-pp-cli messages search <query> — 对消息正文执行全文搜索（当 text 为 NULL 时，从 attributedBody 解码）。标志：--chat、--handle、--from-me、--from-others、--since、--until、--limit。
• icloud-pp-cli messages stats — 消息/聊天/句柄总数、按年份统计，以及排名前 N 的句柄。标志：--top-handles、--include-tapbacks。
• icloud-pp-cli messages export --chat <guid|all> — 将一个聊天（或所有聊天）导出为 JSON，并附上附件路径。标志：--out、--since、--until、--include-tapbacks。

doctor — 使用其他任何命令前运行安装前检查。

Agent 模式

在任何命令后添加 --agent。此选项会展开为 --json --compact --no-color。

icloud-pp-cli photos top --agent
icloud-pp-cli photos storage --agent | jq '.by_year'
icloud-pp-cli photos stats --agent

icloud-pp-cli messages list-chats --limit 10 --agent | jq '[.[] | {chat: .display_name // .chat_identifier, last: .last_message_date}]'
icloud-pp-cli messages search "lunch" --limit 5 --agent
icloud-pp-cli messages stats --agent
icloud-pp-cli messages export --chat <guid> --out /tmp/chat.json

输出始终为 stdout 上的不带颜色的 JSON。便于通过管道传递——命令也会自动检测管道，并在未使用 --agent 时切换为 JSON。Messages JSON 中的每一行都包含 text_source 字段（值为 decoded、text_column 或 unrecoverable），以便 Agent 根据 typedstream 解码器检测覆盖缺口。

常见工作流

查找占用存储空间的内容

# Overview
icloud-pp-cli photos stats

# Breakdown by year and type
icloud-pp-cli photos storage

# Top 25 heaviest files
icloud-pp-cli photos top

# Top 10 largest videos
icloud-pp-cli photos top --limit 10 --type video

查找并删除大文件

# Get UUIDs of top 5 largest videos
icloud-pp-cli photos top --type video --limit 5 --json | jq -r '.[].uuid'

# Dry run — see what would be deleted
icloud-pp-cli photos delete <uuid>

# Actually move to Recently Deleted
icloud-pp-cli photos delete <uuid> --confirm

# Pipe directly
icloud-pp-cli photos top --type video --limit 5 --json \
  | jq -r '.[].uuid' \
  | xargs icloud-pp-cli photos delete --confirm

按年份筛选

# Videos from 2022
icloud-pp-cli photos videos --year 2022 --json

# Videos from January 2022
icloud-pp-cli photos videos --year 2022 --month 1 --json

在聊天历史记录中搜索短语

# Recent messages mentioning "lunch"
icloud-pp-cli messages search "lunch" --since 2026-01-01

# Only messages I sent, last 6 months
icloud-pp-cli messages search "thanks" --from-me --since 2025-11-22

# Find a message in a specific chat
icloud-pp-cli messages search "happy birthday" --chat +15551234567

导出聊天以供后续分析

# One chat to stdout
icloud-pp-cli messages export --chat +15551234567

# One chat to a file
icloud-pp-cli messages export --chat +15551234567 --out /tmp/family.json

# Every chat in one document (large)
icloud-pp-cli messages export --chat all --out /tmp/all-messages.json

退出代码

代码	含义
0	成功
2	用法错误
10	配置错误（操作系统不匹配、未找到库）

直接使用

1. 检查是否已安装：which icloud-pp-cli 如果未找到，请参阅上文的先决条件。
2. 运行诊断：icloud-pp-cli doctor
3. 使用 --agent 执行以输出 JSON：

   icloud-pp-cli <command> [flags] --agent