Skill: liamnichols/icloud-findmy (version 1.0.0)

--- 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 [REDACTED_SECRET] --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: [REDACTED_SECRET] ``` ## 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 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 ```bash 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)

path: README.md
content: # iCloud Find My

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

## What This Skill Does

Teaches your agent how to:
- Query iCloud Find My for device locations
- Check battery levels and charging status
- Monitor family devices
- Provide proactive battery warnings

## Requirements

- macOS (for iCloud API access)
- PyiCloud installed via pipx
- Apple ID with Find My enabled
- Family Sharing (optional, for family devices)

## Installation

```bash
clawdhub install icloud-findmy
```

This will guide you to install PyiCloud. Your agent will then help you authenticate with your Apple ID.

## How It Works

This skill provides documentation and examples for using the `icloud` CLI. Your agent:

1. Stores your Apple ID in its workspace
2. Calls `icloud --username YOUR_ID --with-family --list`
3. Parses the output to extract location and battery data
4. Provides natural language responses

**No custom code required** - just the standard icloud CLI from PyiCloud.

## Session Duration

Sessions last 1-2 months. When expired, your agent will help you re-authenticate.

## Privacy

- Your Apple ID is stored locally in your agent's workspace
- iCloud sessions are stored in your home directory
- No data is sent to third parties
- Uses Apple's standard Find My API

## Examples

**"What's my battery level?"**
→ Agent checks Find My and reports your phone's battery

**"Where is Linda's phone?"**
→ Agent looks up location and provides coordinates or address

**Proactive alerts:**
→ Agent warns if battery is low (<30%) before calendar events

## License

MIT - Uses [PyiCloud](https://github.com/picklepete/pyicloud) by picklepete


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (CRITICAL)