 macOS only

Your entire iCloud,
from the terminal.

icloudcli reads your local SQLite databases directly — Photos, Messages, Contacts, and more. No API token, no login. Find storage hogs, search conversations, export contacts, and automate it all with JSON output.

            ████    ████████████
          ████████████████████████
   ██   ██████████████████████████████
  █████████████████████████████████████
 ███████████████████████████████████████
 ███████████████████████████████████████
  █████████████████████████████████████
    ██████████████████████████████████
         ██████████████████████████

Quick Install

curl -fsSL https://icloudcli.com/install.sh | sh

Get started View on GitHub

Open Source · Apache-2.0

Star

Use cases

What you can do with icloudcli

Every command runs locally against your on-device databases — no network, no app launch. Pipe to jq or use --agent to wire it into any AI workflow.

Find your heaviest files

Every row includes the UUID — copy it straight into photos delete to free space without ever opening Photos.app.

Live

$ icloud-pp-cli photos top --limit 5

# Type Size Date Filename UUID

1 video 9.78 GB 2025-06-19 IMG_2898.MOV 6799AE02-EE45-4469-8AC9-1443582A828E

2 video 4.13 GB 2025-06-28 IMG_2901.MOV C625E37E-F406-435E-B274-67088D9ABF5E

3 video 3.96 GB 2026-05-01 IMG_3668.MOV 4D1C6E68-861D-4512-B09E-5E3D81571A1D

4 video 2.47 GB 2025-01-15 IMG_1262.MOV 02CB886E-51C1-4ED1-81E1-25F1EB275B0D

5 photo 0.84 GB 2024-08-03 RAW_2024-08-03.dng 1A2B3C4D-5E6F-7890-ABCD-EF1234567890

Delete by UUID — no Photos.app needed

Grab UUIDs from photos top, pass them to photos delete. Always a dry run until you add --confirm. Items stay in Recently Deleted for 30 days — fully recoverable.

Live

$ icloud-pp-cli photos delete \ 6799AE02-EE45-4469-8AC9-1443582A828E \ C625E37E-F406-435E-B274-67088D9ABF5E

→ 2025-06-19 IMG_2898.MOV 9.78 GB

→ 2025-06-28 Screen Recording 2025-06-28 at 4.30.51 PM.mov 4.13 GB

Dry run — 2 item(s) would be moved to Recently Deleted.

Add --confirm to proceed.

$ icloud-pp-cli photos delete --confirm \ 6799AE02-EE45-4469-8AC9-1443582A828E \ C625E37E-F406-435E-B274-67088D9ABF5E

✓ moved to Recently Deleted: IMG_2898.MOV

✓ moved to Recently Deleted: Screen Recording 2025-06-28 at 4.30.51 PM.mov

Done — 2 moved, 0 failed.

Open Photos.app → Recently Deleted → Empty to permanently free space.

Pick the right iCloud storage plan

Know your actual library size before upgrading. One number tells you whether you need 200 GB or 2 TB.

Live

$ icloud-pp-cli photos stats --agent | jq '{ items: .total_items, size_gb: .total_size_gb }'

{

"items": 129464,

"size_gb": 794.31

}

→ You need the 2 TB plan.

Find which years are eating the most space

Spot the year that ballooned your library — usually the year you got a new iPhone.

Live

$ icloud-pp-cli photos storage --agent | jq '.by_year | sort_by(-.size_gb) | .[0:5]'

[

{ "label": "2025", "count": 20438, "size_gb": 187.26 },

{ "label": "2024", "count": 18153, "size_gb": 151.17 },

{ "label": "2021", "count": 14559, "size_gb": 123.23 },

{ "label": "2022", "count": 15587, "size_gb": 115.47 },

{ "label": "2020", "count": 17957, "size_gb": 96.28 }

]

Find large videos from a specific time period

Narrow by year and month to target a trip or event. Combine with jq to filter by a size threshold.

Live

$ icloud-pp-cli photos videos --year 2024 --month 8 --agent \ | jq '[.[] | select(.size_gb > 0.5)]'

[

{

"rank": 1, "filename": "IMG_5820.MOV", "size_gb": 1.84,

"date": "2024-08-17", "uuid": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"

{

"rank": 2, "filename": "IMG_5741.MOV", "size_gb": 0.76,

"date": "2024-08-12", "uuid": "B2C3D4E5-F6A7-8901-BCDE-F12345678901"

}

]

Search by location

Find all photos and videos taken in a specific city, neighborhood, or GPS bounding box.

Coming

$ icloud-pp-cli photos search --location "Miami Beach" --type video --agent [ ... videos taken in Miami Beach ... ]

Natural language queries

Ask in plain English. Powered by local embeddings — no data leaves your Mac.

Coming

$ icloud-pp-cli photos ask "vacation videos longer than 2 minutes from last summer" [ ... matching results ... ]

Search by person

List or count photos featuring a named person from your Photos people album.

Coming

$ icloud-pp-cli photos search --person "Mom" --year 2023 --agent [ ... photos featuring Mom from 2023 ... ]

Search your iMessage conversations

Query chat.db directly — search by contact, keyword, or date range. No iCloud API, just the local SQLite database macOS already keeps on your machine.

Coming

$ icloud-pp-cli messages search --from "Mom" --after 2025-01-01 --agent | jq '.[0]' { "chat": "Mom", "date": "2025-06-15", "text": "Are you coming for dinner?", "handle": "+1 (305) 555-0183" }

Export and search your Contacts

Reads the AddressBook SQLite store directly. Export to JSON, search by name or email, pipe into scripts or AI workflows — no Contacts.app, no vCard wrangling.

Coming

$ icloud-pp-cli contacts list --agent | jq '[.[] | {name, email: .emails[0]}][0:3]' [ { "name": "Alex Rivera", "email": "alex@example.com" }, { "name": "Jordan Lee", "email": "jordan@example.com" }, { "name": "Sam Torres", "email": "sam@example.com" } ]

Check your Find My devices

List all devices registered to your Apple ID — name, last-seen timestamp, and battery level — straight from the local Find My cache.

Coming

$ icloud-pp-cli findmy devices Device Last seen Battery iPhone 16 Pro 2 minutes ago 87% MacBook Pro 14 just now charging AirPods Pro 2 1 hour ago 64%

AI workflows

Paste into any AI agent

Copy a prompt, paste it into Claude, Cursor, Codex, or any agent with terminal access — it runs the commands and handles the rest.

Photos

Your best shots. Print-ready.

Curate a year into a photo book — sorted by month, RAW keepers first.

Photos

50 best dog shots. One folder.

Surface dedicated shoot sessions from date clusters and stage them automatically.

Storage

Drop a plan tier. Save $36/yr.

Calculate exactly what to delete to downgrade, with ready-to-run commands.

–2 TB

freed this session

Videos

All your clips. Organized by day.

Find footage from any recording window and stage it for editing.

Storage

3,847 screenshots. Gone.

Find every screenshot, show total wasted space, delete in one shot.

Photos

Your 2024. The 75 best.

Pull RAW and ProRAW keepers from a full year, grouped by quarter.

💡

Community

Have a use case to share?

Write your own prompt and submit it as a pull request — it might end up right here in the slider.

Open GitHub issue

Reference

icloudcli command reference

All commands accept --json, --compact, --no-color, and --agent (sets all three). Use --library to point at a non-default Photos library path.

photos

photos top Top N heaviest files across all media types. Flags: --limit, --type all|photo|video Live

photos videos Largest videos sorted by file size. Flags: --limit, --year, --month Live

photos storage Storage breakdown by media type (photo/video) and by year Live

photos stats Total item count and total library size Live

photos delete Move items to Recently Deleted. Dry run by default; add --confirm to act. Requires Photos.app. Live

photos search Search by location, date range, or person Coming

photos ask Natural language query over your library Coming

messages coming

messages list-chats List all conversations — name, handle, last message date, and message count Coming

messages search Search messages by contact, keyword, or date range. Flags: --from, --text, --after, --before Coming

messages export Export a full conversation thread to JSON or plain text Coming

contacts coming

contacts list List all contacts with filter and sort options. Reads AddressBook SQLite directly. Coming

contacts search Search contacts by name, email, phone, or note Coming

contacts export Export all contacts to JSON — no vCard, no Contacts.app Coming

findmy coming

findmy devices List all Apple ID devices — name, last-seen time, and battery level from local Find My cache Coming

findmy items List AirTags and third-party Find My accessories with last-seen location Coming

root

doctor Pre-flight check — verifies macOS, Photos.app, library path, schema, and asset count. Run this first. Live

Your entire iCloud,
from the terminal.

What you can do with icloudcli

Paste into any AI agent

Leave a star on GitHub.

icloudcli command reference

Install icloudcli on macOS

Your entire iCloud,from the terminal.

What you can do with icloudcli

Paste into any AI agent

Leave a star on GitHub.

icloudcli command reference

Install icloudcli on macOS

Your entire iCloud,
from the terminal.