icloud-findmy

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

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 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:
```markdown
## iCloud Find My
Apple ID: their.email@example.com
```

## Usage

### List all devices

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