Media and Entertainment

Apple iCloud

icloud-pp-cli

Query iCloud data stored locally on macOS — Photos library storage analysis, with Contacts and more coming. All reads hit local SQLite databases directly; no network calls or iCloud API token required.

Printed by @matysanchez (Matias Sanchez Moises)

Install

npx — recommended

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

Installs the CLI binary and the agent skill (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and more). Add --cli-only or --skill-only for one half. Requires Node.

Hermes

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-icloud --force

From the Hermes CLI. Inside a chat session use /skills install with the same path.

OpenClaw

Install the pp-icloud skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-icloud. The skill defines how its required CLI can be installed.

Paste this to your OpenClaw agent — the skill describes how to install its CLI.

View source on GitHub →

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:

Fork the library repo
Copy cmd/, internal/, go.mod, go.sum, LICENSE, SKILL.md, .printing-press.json into library/media/icloud/
Update go.mod module to github.com/mvanhorn/printing-press-library/library/media/icloud
Update the import in cmd/icloud-pp-cli/main.go to match
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