Your Apple devices' location, via CLI — for AI agents and humans.

🇬🇧 English · 🇮🇹 Italiano

---

What is it?

FindMyPipe is a local CLI bridge that queries Apple Find My from Linux and returns device locations as structured JSON, ready for AI agents, shell scripts, and automation pipelines.

Beyond simply knowing where your devices are, findmypipe is designed to power location-aware workflows: given the coordinates of a device, an AI agent can query external services to find nearby points of interest — restaurants, hotels, hospitals, transit stops — and build richer, context-aware experiences.

"Where's my iPhone?" · "Is my MacBook at home?" · "Find a coffee shop near my AirPods" · "What's the nearest hospital to my iPad?"

---

✨ Features

Feature	Description
🔍 Locate Apple devices	iPhone, iPad, Mac, AirPods — real-time position via iCloud
📍 Points of interest nearby	Feed coordinates to any POI API (Google Places, OSM, Foursquare) to find what's around your device
🖥️ Professional CLI	Clean structured JSON output on stdout, easy to pipe and parse
🔐 Privacy-first	Redacted credentials in logs, device IDs replaced by SHA-256 hash
📦 Zero configuration	Mock mode works out of the box — no Apple ID needed to explore
⏱️ Optional cache	Configurable TTL to avoid hammering the iCloud API
🧹 Smart filters	--skip-offline and --max-age to keep only fresh, relevant data
🔄 Full 2FA login	Complete Apple authentication flow, interactive 2FA included
🤖 AI agent-ready	Designed as an AgentSkills.io-compliant skill — plug it into any agent framework

---

🤖 What is an AgentSkills.io Skill?

FindMyPipe ships with a SKILL.md definition conforming to the AgentSkills.io standard. This means:

• Any AI agent framework that supports the standard can automatically discover and invoke this tool
• The skill is self-describing: it declares its inputs, outputs, and capabilities in a machine-readable format
• It integrates seamlessly with agents like Hermes, custom LLM pipelines, or any shell-capable orchestrator

Think of it as an OpenAPI spec, but for AI agent tools.

---

💡 Use Cases

🗺️ Find points of interest near your device

# Get your iPhone's coordinates
COORDS=$(findmy-agent locate "iPhone" --json | jq -r '"\(.asset.latitude),\(.asset.longitude)"')

# Query nearby restaurants (example with Google Places API)
curl "https://maps.googleapis.com/maps/api/place/nearbysearch/json\
?location=$COORDS&radius=500&type=restaurant&key=$GOOGLE_API_KEY" | jq '.results[].name'

📍 Check if a device is home

findmy-agent locate "MacBook" --json | jq '.asset | {name, latitude, longitude, last_seen}'

🔔 Periodic monitoring via cron

# Every 15 minutes, log all online devices
*/15 * * * * findmy-agent list --json --skip-offline >> /var/log/findmy.log

🤖 AI agent integration (Hermes)

# ~/.hermes/config.yaml
tools:
  - name: findmy_locate
    cmd: "findmy-agent locate \"{{name}}\" --json"
  - name: findmy_list
    cmd: "findmy-agent list --json --skip-offline"
  - name: findmy_doctor
    cmd: "findmy-agent doctor --json"

---

📦 Installation

Prerequisites

• Python 3.11+
• Linux (tested) or macOS
• An Apple ID with Find My enabled (live mode only)

Quick install

git clone https://github.com/corryl/FindMyPipe.git
cd FindMyPipe
python3 -m venv .venv

# Mock mode only (works immediately, no Apple ID needed)
.venv/bin/pip install -e '.[dev]'

# With live iCloud support
.venv/bin/pip install -e '.[dev,live]'

# Verify installation
.venv/bin/findmy-agent doctor --json

Expected output:

{
  "cache": {"enabled": false, "state": "empty", "ttl_seconds": 0},
  "live_probe_available": true,
  "ok": true,
  "provider": "mock",
  "secrets_redacted": true,
  "transport": "local"
}

---

⚙️ Configuration

Live iCloud mode

export FINDMY_AGENT_PROVIDER="icloud"
export FINDMY_APPLE_ID="[REDACTED]"
export FINDMY_APPLE_PASSWORD="[REDACTED]"

🔐 Use an app-specific password — Apple ID → Security → App-Specific Passwords. Never use your main Apple ID password.

Optional settings

export FINDMY_COOKIE_DIR="$HOME/.local/state/findmypipe/icloud"
export FINDMY_CACHE_TTL="300"       # seconds (0 = disabled)
export FINDMY_CACHE_FILE="$HOME/.local/state/findmypipe/cache.json"

Interactive login (first run)

findmy-agent login --json
# Type your 2FA code when Apple sends it

---

🖥️ CLI Reference

All commands accept --json for structured output.

findmy-agent doctor

Check bridge status and provider availability.

findmy-agent doctor --json
findmy-agent doctor --provider icloud --json

findmy-agent list

List all devices with location, battery level, and last seen time.

findmy-agent list --json
findmy-agent list --json --skip-offline --max-age 30
findmy-agent list --json --include-raw

Example output

{
  "assets": [{
    "id": "icloud:a1b2c3d4e5f6a7b8",
    "name": "iPhone",
    "kind": "device",
    "provider": "icloud",
    "latitude": 45.1234,
    "longitude": 9.5678,
    "accuracy_m": 15.0,
    "battery": 0.85,
    "battery_status": "charged",
    "last_seen": "2025-05-30T12:34:56Z",
    "location_is_old": false
  }]
}

findmy-agent locate

Search for a specific device by name or ID (case-insensitive).

findmy-agent locate "iPhone" --json
findmy-agent locate "AirPods" --json --skip-offline --max-age 60

findmy-agent login

Interactive iCloud authentication with 2FA.

findmy-agent login --json

Common options

Option	Description
--provider	mock (default) or icloud
--json	Structured JSON output
--include-raw	Include redacted raw payload (debug)
--max-age <min>	Filter positions older than N minutes
--skip-offline	Exclude offline devices

Error format

All errors return a consistent structured format:

{"error": "FINDMY_APPLE_ID not set", "error_type": "configuration_error", "ok": false, "secret_safe": true}

---

🔐 Privacy & Security

• No HTTP server — all I/O on stdio, no open ports, no daemon
• No webhooks — outbound polling only toward Apple's servers
• Credentials never logged — password, 2FA codes, and tokens always redacted
• Hashed device IDs — real identifiers replaced by SHA-256 hash in all output
• Raw payload hidden by default — requires explicit --include-raw flag
• Restrictive file permissions — directories 0700, files 0600

~/.local/state/findmypipe/
├── icloud/        # Cookies & sessions (0700)
└── cache.json     # Optional cache (0600)

---

🏗️ Architecture

┌──────────────────────────────────────┐
│   AI Agent / Shell Script / Terminal  │
└────────────┬─────────────────────────┘
             │  CLI (stdin/stdout/stderr)
┌────────────▼─────────────────────────┐
│           findmy-agent               │
│                                      │
│  ┌──────────┐   ┌──────────────────┐ │
│  │   CLI    │   │     Cache        │ │
│  │ (Typer)  │   │  (JSON file)     │ │
│  └────┬─────┘   └──────────────────┘ │
│       │                              │
│  ┌────▼──────┐                       │
│  │   Core    │                       │
│  └────┬──────┘                       │
│       │                              │
│  ┌────▼──────┐                       │
│  │ Provider  │                       │
│  │ Mock│iCld │                       │
│  └───────────┘                       │
└────────────┬─────────────────────────┘
             │ HTTPS (outbound only)
┌────────────▼─────────────────────────┐
│         Apple iCloud API             │
└──────────────────────────────────────┘

---

🧪 Tests

.venv/bin/pytest -q --tb=short

tests/test_cache.py ..........
tests/test_cli.py ....
tests/test_core.py ........
tests/test_icloud_provider.py ...
tests/test_provider_factory.py ...
31 passed

---

📋 Limits & Roadmap

Aspect	Status
iPhone, iPad, Mac, AirPods	✅ Supported
AirTag / Items	⏳ Not yet supported
Linux	✅ Tested
macOS	✅ Should work
Interactive 2FA	✅ Supported
POI integration (built-in)	⏳ Planned

---

📄 License

MIT — see LICENSE.

---

_{Built with ❤️ for the AI community · AgentSkills.io · Skill Definition
Local. Secure. Private. Your data, under your control.}