Agent skill

Icloud Pp CLI

by mvanhorn in mvanhorn/printing-press-library

Query your Apple iCloud data from the command line — Photos library storage analysis, iMessage history search and export, largest-file finder, and delete via AppleScript.

Apache-2.0Auto-check: notesProductivity & Automation

Install Icloud Pp CLI

skills CLI
$ npx skills add mvanhorn/printing-press-library --skill icloud-pp-cli -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install mvanhorn/printing-press-library icloud-pp-cli --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/mvanhorn/printing-press-library.git skills-src && mkdir -p .claude/skills && cp -r skills-src/cli-skills/pp-icloud .claude/skills/icloud-pp-cli && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
icloud-pp-cli
GitHub stars
2.1k
Token cost
~1.9k tokens
SKILL.md length
542 words
Files
1
Skills in repo
505
Repo updated
First seen
Licence
Apache-2.0

At a glance

Query your Apple iCloud data from the command line — Photos library storage analysis, iMessage history search and export, largest-file finder, and delete via AppleScript.

  • Works in 3 steps: Install via the Printing Press… → Verify: icloud-pp-cli --version → Ensure the reported install directory is…
  • Tasks that involve Messaging and chat bots
  • SKILL.md covers Prerequisites: Install the CLI, Pre-flight Check, Messages: Full Disk Access… and Command Reference, plus 4 more sections
  • Calls jq, npx and go

What it does

Icloud Pp CLI is an agent skill from mvanhorn/printing-press-library. Query your Apple iCloud data from the command line — Photos library storage analysis, iMessage history search and export, largest-file finder, and delete via AppleScript. macOS only. No network calls or iCloud API token required.

Its SKILL.md is about 1.9k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Productivity & Automation, covering Messaging and chat bots. It works with macOS. The repository describes itself as: Official library of CLIs generated by the CLI Printing Press. Endorsed, tested, and community-contributed. The licence is Apache-2.0.

When your agent uses it

  • Tasks that involve Messaging and chat bots

Example prompts

  • “/icloud-pp-cli”

Requirements

  • Node.js
  • Pre-approved tools (allowed-tools): Read, Bash

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and…
  2. Verify: icloud-pp-cli --version
  3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

What it can do on your machine

Read from SKILL.md and the folder at commit 0fdcc7a. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Read
    • Bash

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • jq
    • npx
    • go

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use npx, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Icloud Pp CLI loads about 1.9k tokens when it runs. Until then it costs about 61 tokens; SKILL.md has 542 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~61
When it runs · the whole SKILL.md, loaded when a task matches
~1.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
    allowed-tools: Read, Bash

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from mvanhorn/printing-press-library at commit 0fdcc7a, republished under its Apache-2.0 licence (© mvanhorn). 542 words, ~1,857 tokens.

Download SKILL.mdSave it as .claude/skills/icloud-pp-cli/SKILL.md (or your agent's skills folder).
name
icloud-pp-cli
description
Query your Apple iCloud data from the command line — Photos library storage analysis, iMessage history search and export, largest-file finder, and delete via AppleScript. macOS only. No network calls or iCloud API token required.
allowed-tools
Read, Bash
author
Matias Sanchez Moises
license
Apache-2.0
argument-hint
<command> [args] | install
<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/media-and-entertainment/icloud/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

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:
    bash
    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):

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

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

bash
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).
Show full SKILL.md (220 more words)Show less

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.

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

CodeMeaning
0Success
2Usage error
10Config 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:
    bash
    icloud-pp-cli <command> [flags] --agent

© mvanhorn, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in cli-skills/pp-icloud of mvanhorn/printing-press-library.

Open the folder on GitHubat commit 0fdcc7a

Compare with similar skills

Icloud Pp CLI next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Icloud Pp CLI compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Icloud Pp CLI this skillmvanhorn/printing-press-library2.1k—~1.9kAutomated safety check: NotesApache-2.0
Slack Messaginghaojing8312/WorkClaw141—~897Automated safety check: PassApache-2.0
Imsggeezerrrr/motive1158 repos~273Automated safety check: PassMIT
ImessageRedWoodOG/Hermes-Desktop1774 repos~606Automated safety check: PassMIT
Prismer ImessagePrismer-AI/PrismerCloud1.6k—~962Automated safety check: PassMIT
Yichen Mac Wechat Dual Openmcncarl/yichen-skills4.3k—~1.5kAutomated safety check: PassCustom licence

Similar skills

  • Slack Messaging

    haojing8312/WorkClaw

    A skill your agent uses when asked to send or read Slack messages, check Slack channels, test Slack integrations, or interact with a Slack workspace from the command line.

    141 GitHub stars~897 tokensUpdated 4 mo ago
    Productivity & AutomationAuto-check passed
  • Imsg

    geezerrrr/motive

    iMessage/SMS CLI for listing chats, history, watch, and sending.

    115 GitHub starsUsed in 8 repos~273 tokens
    Productivity & AutomationAuto-check passed
  • Imessage

    RedWoodOG/Hermes-Desktop

    Send and receive iMessages/SMS via the imsg CLI on macOS. An agent skill from RedWoodOG/Hermes-Desktop.

    177 GitHub starsUsed in 4 repos~606 tokens
    Productivity & AutomationAuto-check passed
  • Prismer Imessage

    Prismer-AI/PrismerCloud

    Send and receive iMessages/SMS via the imsg CLI on macOS. An agent skill from Prismer-AI/PrismerCloud.

    1.6k GitHub stars~962 tokensUpdated 8 days ago
    Productivity & AutomationAuto-check passed
  • Yichen Mac Wechat Dual Open

    mcncarl/yichen-skills

    Create, inspect, repair, and polish a second WeChat app on macOS by copying WeChat, changing the bundle identifier, ad-hoc re-signing, preparing it for the user to open manually, setting Chinese…

    4.3k GitHub stars~1.5k tokensUpdated 4 days ago
    Productivity & AutomationAuto-check passed
  • Feishu Bridge

    AlexAnys/feishu-openclaw

    Connect a Feishu (Lark) bot to Clawdbot via WebSocket long-connection.

    317 GitHub starsUsed in 1 repo~615 tokens
    Productivity & AutomationAuto-check passed

More from mvanhorn/printing-press-library

All 505 skills in this repo
  • Agent Desktop

    mvanhorn/printing-press-library

    Desktop automation through the real Rust agent-desktop CLI, published in Printing Press through a small bridge.

    2.1k GitHub stars~2.3k tokensUpdated yesterday
    Auto-check: notes
  • Gfonts

    mvanhorn/printing-press-library

    Search, browse, and download Google Fonts from the terminal via the gfonts CLI.

    2.1k GitHub stars~574 tokensUpdated yesterday
    Auto-check passed
  • Pp 1688

    mvanhorn/printing-press-library

    The free, offline Trigger phrases: search 1688 for, find a factory on 1688 for, wholesale price on 1688 for, who is the cheapest supplier on 1688 for, compare 1688 suppliers for, use 1688, run 1688.

    2.1k GitHub stars~3k tokensUpdated yesterday
    Auto-check: notes
  • Pp Activity Japan

    mvanhorn/printing-press-library

    Inspect known Activity Japan plan IDs or URLs, compare dated prices and sessions, check language-sitemap coverage, and hand off to canonical booking pages.

    2.1k GitHub stars~2k tokensUpdated yesterday
    Auto-check: notes
  • Pp Adminbyrequest

    mvanhorn/printing-press-library

    Every Admin By Request portal action, plus a local SQLite mirror of audit, events, inventory and requests for ad-hoc...

    2.1k GitHub stars~3.3k tokensUpdated yesterday
    Auto-check: notes
  • Pp Agent Capture

    mvanhorn/printing-press-library

    macOS screen capture, window recording, GIF conversion, and agent evidence bundles from the terminal.

    2.1k GitHub stars~1.6k tokensUpdated yesterday
    Auto-check: notes

Works with

Questions about Icloud Pp CLI

What does Icloud Pp CLI do?

Query your Apple iCloud data from the command line — Photos library storage analysis, iMessage history search and export, largest-file finder, and delete via AppleScript. Icloud Pp CLI is an agent skill from mvanhorn/printing-press-library. Query your Apple iCloud data from the command line — Photos library storage analysis, iMessage history search and export, largest-file finder, and delete via AppleScript.

When should I use Icloud Pp CLI?

Icloud Pp CLI fits situations like: tasks that involve Messaging and chat bots.

How do I install Icloud Pp CLI in Claude Code?

Run `npx skills add mvanhorn/printing-press-library --skill icloud-pp-cli -a claude-code`. Or copy the skill folder (cli-skills/pp-icloud in mvanhorn/printing-press-library) into .claude/skills/icloud-pp-cli in your project. Claude Code loads it when a task matches its description.

How do I install Icloud Pp CLI in Codex?

Run `npx skills add mvanhorn/printing-press-library --skill icloud-pp-cli -a codex`. Or copy the skill folder (cli-skills/pp-icloud in mvanhorn/printing-press-library) into .agents/skills/icloud-pp-cli in your project. Codex loads it when a task matches its description.

Can I use Icloud Pp CLI in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add mvanhorn/printing-press-library --skill icloud-pp-cli -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/icloud-pp-cli, .gemini/skills/icloud-pp-cli, .github/skills/icloud-pp-cli and .opencode/skills/icloud-pp-cli in your project.

What does Icloud Pp CLI need to run?

Going by SKILL.md and its folder, Icloud Pp CLI needs the command-line tools its instructions call (jq, npx and go). Our summary lists: Node.js. Its frontmatter pre-approves these tools: Read, Bash.

Does Icloud Pp CLI access the network?

SKILL.md contains no URLs. Its commands use npx, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Icloud Pp CLI safe to install?

Our automated static check of SKILL.md found notes only (pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Icloud Pp CLI use?

Icloud Pp CLI is published under the Apache-2.0 licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Icloud Pp CLI use?

About 1.9k tokens (SKILL.md is roughly 7.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Icloud Pp CLI?

Skills that share tags, products or a category with Icloud Pp CLI: Slack Messaging (haojing8312/WorkClaw, 141 stars), Imsg (geezerrrr/motive, 115 stars), Imessage (RedWoodOG/Hermes-Desktop, 177 stars) and Prismer Imessage (Prismer-AI/PrismerCloud, 1.6k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Icloud Pp CLI?

mvanhorn (a GitHub user) maintains it in mvanhorn/printing-press-library, which has 2,053 GitHub stars. The repository holds 505 skills in this directory. The repository was last updated on October 7, 2026.

Source: mvanhorn/printing-press-library on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.