icloud-findmy

iCloud Find My

Access Find My device locations and battery status via the iCloud CLI (pyicloud).

Setup

1. Install pyicloud:

brew install pipx
pipx install pyicloud

2. Authenticate (one-time):

Ask the user for their Apple ID, then run:

icloud --username their.email@example.com --with-family --list

They'll need to enter their password and complete 2FA. The session will be saved and lasts 1-2 months.

3. Store Apple ID:

Add the Apple ID to your TOOLS.md or workspace config so you remember it for future queries:

## iCloud Find My
Apple ID: their.email@example.com

Usage

List all devices

icloud --username APPLE_ID --with-family --list

Output format:

------------------------------
Name           - Liam's iPhone
Display Name   - iPhone 15 Pro
Location       - {'latitude': 52.248, 'longitude': 0.761, 'timeStamp': 1767810759054, ...}
Battery Level  - 0.72
Battery Status - NotCharging
Device Class   - iPhone
------------------------------

Parsing tips:

• Devices are separated by ------------------------------
• Location is a Python dict (use eval() or parse with regex)
• Battery Level is 0.0-1.0 (multiply by 100 for percentage)
• Battery Status: "Charging" or "NotCharging"
• Location fields: latitude, longitude, timeStamp (milliseconds), horizontalAccuracy

Get specific device

Find a specific device by grepping the output:

icloud --username APPLE_ID --with-family --list | grep -A 10 "iPhone"

Parse location

Extract and format location data:

icloud --username APPLE_ID --with-family --list | \
  grep -A 10 "Device Name" | \
  grep "Location" | \
  sed "s/Location.*- //"

Then parse the Python dict string with Python or extract coordinates with regex.

Parse battery

icloud --username APPLE_ID --with-family --list | \
  grep -A 10 "Device Name" | \
  grep "Battery Level"

Device Names

Device names come from iCloud and may include:

• Fancy Unicode apostrophes (U+2019 ') instead of ASCII '
• No apostrophes at all (e.g., "Lindas iPhone")

Use case-insensitive matching and normalize apostrophes if needed.

Session Management

• Sessions last 1-2 months
• Stored in user's home directory
• When expired, re-run the authentication step
• PyiCloud validates automatically on each request

Common Patterns