Media and Entertainment

iCloud

pp-icloud

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 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

Quick start

icloud-pp-cli doctor              # verify library is readable
icloud-pp-cli photos top          # top 25 heaviest files
icloud-pp-cli photos storage      # breakdown by type and year
icloud-pp-cli photos stats        # total size + item count

Pipe any command for automatic JSON:

icloud-pp-cli photos top | jq '.[0:5]'

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
  doctor       Verify Photos library is readable

All commands accept: --json --compact --no-color --agent --library PATH

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

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