Apple iCloud CLI

Query your Apple iCloud data from the command line. Reads your Mac's local databases directly — no Photos.app launch, no API token, no network calls.

icloudcli.com · macOS · Apache-2.0

---

Created by @matysanchez (Matias Sanchez Moises).

Quick start

icloud-pp-cli doctor                            # verify Photos + Messages access
icloud-pp-cli photos top                        # top 25 heaviest files
icloud-pp-cli messages list-chats --limit 10    # 10 most-recently-active chats
icloud-pp-cli messages search "lunch"           # search your message history

Pipe any command for automatic JSON:

icloud-pp-cli photos top | jq '.[0:5]'
icloud-pp-cli messages list-chats --agent | jq '[.[] | select(.is_group)]'

---

Commands

icloud-pp-cli
  photos
    top         Top N heaviest files (--limit, --type all|photo|video)
    videos      Largest videos (--limit, --year, --month)
    storage     Breakdown by media type and year
    stats       Total items and library size
    delete      Move items to Recently Deleted (requires --confirm)
    download    Export originals to a local folder
  messages
    list-chats  Chats ordered by most-recent activity (--limit, --since, --include-empty)
    search      Full-text search of message bodies (--chat, --handle, --from-me, --since, --until, --limit)
    stats       Total messages / chats / handles + by-year + top handles
    export      Export a chat or all chats to JSON (--chat, --out, --since, --until)
  doctor        Pre-flight: System / Library / Assets / Messages

All commands accept: --json --compact --no-color --agent. photos commands also accept --library PATH; messages commands accept --messages-db PATH.

--agent sets --json --compact --no-color in one flag — use it in AI workflows.

Messages: Full Disk Access required

Reading ~/Library/Messages/chat.db requires macOS Full Disk Access 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 this automatically — the Messages section shows green when FDA is granted and a yellow warning (with remediation) when it is not.

---

Repository layout

icloudcli/
  cmd/icloud-pp-cli/   Go binary entry point
  internal/cli/        Command implementations and Photos SQLite reader
  web/                 Landing page (deployed to icloudcli.com via Cloudflare Pages)
  go.mod               module: github.com/matysanchez/icloudcli

Submitting to Printing Press

To submit a snapshot to printing-press-library:

1. Fork the library repo
2. Copy cmd/, internal/, go.mod, go.sum, LICENSE, SKILL.md, .printing-press.json into library/media/icloud/
3. Update go.mod module to github.com/mvanhorn/printing-press-library/library/media/icloud
4. Update the import in cmd/icloud-pp-cli/main.go to match
5. Open a PR with commit message: feat(icloud): add icloud-pp-cli

---

Contributing

Issues and PRs welcome. This repo is the source of truth — the Printing Press submission is a periodic snapshot with its module path updated.

License

Apache-2.0