icloud-pp-cli

Apple iCloud — CLI Skill

Prerequisites: Install the CLI

This skill drives the icloud-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

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

2. Verify: icloud-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer):

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

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

Pre-flight Check

Always run doctor first to confirm your setup:

icloud-pp-cli doctor

Verifies: macOS, Photos.app installed, library path found, database schema valid, asset count queryable, chat.db readable (Full Disk Access).

If your Photos library is in a non-default location:

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

Messages: Full Disk Access required

messages subcommands read ~/Library/Messages/chat.db directly, which on macOS requires Full Disk Access (FDA) for the terminal app invoking the binary. If a messages command fails with "Full Disk Access not granted", open System Settings > Privacy & Security > Full Disk Access, add your terminal, quit and reopen the terminal, and rerun. doctor reports FDA state automatically.

Command Reference

photos — Query and manage your Photos library.

• icloud-pp-cli photos stats — Quick summary: total items and total library size.
• icloud-pp-cli photos storage — Storage breakdown by media type (photo/video) and by year.
• icloud-pp-cli photos top — Top heaviest files across all media types.
• icloud-pp-cli photos videos — List your largest videos sorted by file size.
• icloud-pp-cli photos delete <uuid...> — Move items to Recently Deleted in Photos.app (requires --confirm).
• icloud-pp-cli photos download [uuid...] --output <dir> — Export originals from iCloud to a local folder. Photos.app downloads from iCloud automatically if Optimize Mac Storage is enabled.
• icloud-pp-cli photos download --sensitive --confirm --output <dir> — Export items Apple's on-device ML has flagged as containing nudity (--confirm required).

messages — Read your iMessage history from ~/Library/Messages/chat.db. Requires Full Disk Access.

• icloud-pp-cli messages list-chats — Chats ordered by most-recent activity. Flags: --limit, --since, --include-empty.
• icloud-pp-cli messages search <query> — Full-text search across message bodies (decoded from attributedBody when text is NULL). Flags: --chat, --handle, --from-me, --from-others, --since, --until, --limit.
• icloud-pp-cli messages stats — Total messages / chats / handles, by-year breakdown, top N handles. Flags: --top-handles, --include-tapbacks.
• icloud-pp-cli messages export --chat <guid|all> — Export a chat (or every chat) to JSON with attachment paths. Flags: --out, --since, --until, --include-tapbacks.

doctor — Run pre-flight checks before using any other command.

Agent Mode

Add --agent to any command. Expands to --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

Output is always JSON on stdout with no color. Pipe-friendly — commands also auto-detect pipes and switch to JSON without --agent. Messages JSON includes a text_source field on every row (decoded, text_column, or unrecoverable) so agents can detect coverage gaps from the typedstream decoder.

Common Workflows

Find what's eating storage

# 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

Identify and delete large files

# 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

Filter by year

# 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

Search a chat history for a phrase

# 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

Export a chat for downstream analysis

# 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

Exit Codes

Code	Meaning
0	Success
2	Usage error
10	Config error (wrong OS, library not found)

Direct Use

1. Check installation: which icloud-pp-cli If missing, see Prerequisites above.
2. Run doctor: icloud-pp-cli doctor
3. Execute with --agent for JSON output:

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