- name
- icloud-findmy
- description
- Query Find My locations and battery status for family devices via iCloud.
- homepage
- https://github.com/picklepete/pyicloud
- metadata
- {"clawdbot":{"emoji":"📍","requires":{"bins":["icloud"]},"install":[{"id":"pipx","kind":"shell","command":"brew install pipx && pipx install pyicloud","bins":["icloud"],"label":"Install PyiCloud (pipx)"}]}}
iCloud Find My
Access Find My device locations and battery status via the iCloud CLI (pyicloud).
Setup
- Install pyicloud:
brew install pipx
pipx install pyicloud- Authenticate (one-time):
Ask the user for their Apple ID, then run:
icloud --username their.email@example.com --with-family --listThey'll need to enter their password and complete 2FA. The session will be saved and lasts 1-2 months.
- 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.comUsage
List all devices
icloud --username APPLE_ID --with-family --listOutput 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
Check battery before going out:
# Get battery for specific device
icloud --username ID --with-family --list | \
grep -B 2 -A 5 "iPhone" | \
grep "Battery Level"Get current location:
# Extract location dict and parse coordinates
icloud --username ID --with-family --list | \
grep -A 10 "iPhone" | \
grep "Location" | \
sed "s/.*- //" | \
python3 -c "import sys; loc = eval(sys.stdin.read()); print(f\"{loc['latitude']}, {loc['longitude']}\")"Check if device is charging:
icloud --username ID --with-family --list | \
grep -A 10 "iPhone" | \
grep "Battery Status"Proactive Use Cases
- Battery warnings: Check battery levels before calendar events (going out)
- Location context: Answer "near me" queries by checking user's current location
- Home/away detection: Check if user is at home based on coordinates
- Low battery alerts: Warn if battery <30% and not charging
Troubleshooting
Authentication errors:
- Session expired - re-authenticate
- Wrong Apple ID - check stored ID
- 2FA required - complete 2FA flow
No location available:
- Device offline
- Find My disabled
- Location Services off
Device not found:
- Check exact device name with
--list - Names are case-sensitive
- May have Unicode apostrophes
Notes
- Requires macOS (iCloud API quirks)
- Family Sharing must be enabled to see family devices
- Location updates every ~1-5 minutes when device is active
- Battery readings may be cached (check timestamp)