iCloud Find My

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

Setup

1. Install pyicloud: bash brew install pipx pipx install pyicloud

2. Authenticate (one-time):

Ask the user for their Apple ID, then run: bash icloud --username [email protected] --with-family --list

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

1. Store Apple ID:

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

iCloud Find My

Apple ID: [email protected] ```

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:
```bash
icloud --username APPLE_ID --with-family --list | grep -A 10 "iPhone"

Parse location

Extract and format location data: bash 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: ```bash

Get battery for specific device

icloud --username ID --with-family --list | \ grep -B 2 -A 5 "iPhone" | \ grep "Battery Level" ```

Get current location: ```bash

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