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. 報告されたインストールディレクトリが、このスキルを実行するエージェント／ランタイムの $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 サブコマンドは ~/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 を追加します。--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

標準出力には常に、色なしの JSON が出力されます。パイプでの利用に対応しており、--agent を指定しなくてもコマンドはパイプを自動検出して JSON に切り替わります。Messages の JSON には各行に text_source フィールド（decoded、text_column、または unrecoverable）が含まれるため、エージェントは 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	設定エラー（OS が正しくない、ライブラリが見つからない）

直接使用する

1. インストールを確認します：which icloud-pp-cli 見つからない場合は、上記の前提条件を参照してください。
2. doctor を実行します：icloud-pp-cli doctor
3. JSON 出力には --agent を指定して実行します：

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