Find My iCloud CLI

Query Apple Find My device and family-device locations through the pyicloud iCloud CLI, using a locally stored Apple ID username in a deterministic state fil...

Security Scan

The skill's requirements and scripts are consistent with its stated purpose (a local wrapper around the pyicloud/icloud CLI) with a few minor implementation inconsistencies to review before use.

Purpose & Capability

Name/description match the included scripts: the Python and shell scripts call the local 'icloud' CLI to list and show devices and manage a local username and alias state. Asking for no cloud credentials and relying on the local pyicloud auth flow is appropriate for this purpose.

Instruction Scope

SKILL.md and scripts instruct the agent to read/write per-user state files (~/.local/state/icloud-findmy-cli/) and to run the local 'icloud' CLI. No instructions attempt to read unrelated system files or exfiltrate data to third-party endpoints. Minor issues: SKILL.md suggests cd into a developer-specific path (/Users/rolandk/...) which is environment-specific and unnecessary; several error messages point to a non-existent './scripts/account-set.sh' (should be './scripts/findmy.sh set-username'), which is an inconsistency to fix.

Install Mechanism

There is no install spec (instruction-only), which minimizes install risk. However the scripts implicitly require the 'icloud' CLI (pyicloud >= 2.5.0) to be present — that dependency is documented in SKILL.md but not enforced. The skill does not download or execute remote code itself.

Credentials

The skill requests no environment variables or external credentials. It persistently stores only the Apple ID username (email) in a local state file and directs the user to complete auth interactively (password/2FA) via the pyicloud flow. This access pattern is proportionate to the stated function. Users should note the username is stored in cleartext in ~/.local/state/icloud-findmy-cli/account.env.

Persistence & Privilege

The skill does not request always:true, does not modify other skills, and only writes to its own state directory under the user's home. It can be invoked autonomously (platform default), which is expected for skills; this combined with its limited local state is not a high privilege concern.

Assessment

This skill appears to do exactly what it says: wrap the local pyicloud 'icloud' CLI and store a single Apple ID email in ~/.local/state/icloud-findmy-cli/account.env. Before installing: (1) ensure you trust and have installed the 'icloud' (pyicloud) CLI from a verified source; (2) be aware the skill will persist your Apple ID email in plain text under ~/.local/state — it does not store passwords but will open the standard pyicloud auth flow for interactive login (password + 2FA) that goes to Apple's servers; (3) note small implementation issues (developer path in SKILL.md and incorrect error messages referencing './scripts/account-set.sh') — you may want to correct those before using; (4) review the scripts yourself to confirm they call only the local 'icloud' binary and do not add remote endpoints. If you need stronger guarantees, run the scripts in a sandboxed account or verify the 'icloud' binary provenance first.

Use this skill for Apple Find My lookups via the icloud CLI (pyicloud 2.5.0+). This is the reliable path for device and family-device location on this Mac.

Run scripts from:

cd /Users/rolandk/.openclaw/workspace/skills/findmy-icloud-cli

State and setup

Do not hardcode the user's Apple ID in the skill. Store it once in this deterministic state file:

~/.local/state/icloud-findmy-cli/account.env

Format:

ICLOUD_FINDMY_USERNAME="[e-mail]"

Use:

./scripts/findmy.sh set-username [e-mail]
./scripts/findmy.sh show-username

If the username is missing, stop and ask the user once for their Apple ID email. After that, persist it via findmy.sh set-username and reuse the state file.

Auth flow

Check current auth:

./scripts/findmy.sh auth-status

If not logged in:

./scripts/findmy.sh auth-login

That opens the current pyicloud auth flow using the stored username. The user may need to enter password and 2FA.

Core commands

Resolve a person to the best device automatically

When the user asks for a person's location in natural language, do not force them to name a device. Use scripts/person-find.py first.

Do not hardcode real family names into the skill. Store person aliases in a local state file instead:

~/.local/state/icloud-findmy-cli/people-aliases.json

Set aliases with neutral labels such as me, partner, kid, or any user-chosen nickname:

./scripts/findmy.sh set-person-alias me "Roland"
./scripts/findmy.sh set-person-alias partner "Gabriella"
./scripts/findmy.sh show-person-aliases

Default resolution order:

1. Match the person's iPhone
2. If no matching iPhone with location is available, match their Apple Watch
3. If neither is available, fall back to another matching device
4. If nothing matches, say so clearly

Examples:

./scripts/person-find.py "partner"
./scripts/person-find.py "me"
./scripts/person-find.py "kid"

List all devices with live location

./scripts/findmy.sh list

This runs:

icloud devices list --username "$USERNAME" --with-family --locate --format json

Show one device in detail

./scripts/findmy.sh show "Roland’s iPhone 14 Pro"

Find devices by fuzzy name match

./scripts/device-find.py "Gabriella"
./scripts/device-find.py "iPhone 14"

Output shape

The main command returns JSON list entries with fields like:

• id
• name
• display_name
• device_class
• device_model
• battery_level
• battery_status
• location.latitude
• location.longitude
• location.timeStamp
• location.horizontalAccuracy

Prefer JSON parsing over text scraping.

Working rules

• Use this skill for Apple devices and family-shared devices, not shared-person Find My contacts.
• If the user asks for a person like "where is my partner?", use scripts/person-find.py instead of asking for a device name.
• Prefer user-defined aliases from people-aliases.json, not hardcoded real names in the skill.
• Prefer iPhone first, then Apple Watch, then other matching devices.
• Prefer findmy.sh list first when broad inspection is needed.
• Use findmy.sh show when the exact device name is already known.
• If auth breaks after an upgrade, re-check with icloud --help, then re-run findmy.sh auth-login.
• Do not ask for the Apple ID again if the state file already has it.
• Do not store passwords in the state file.

Limits

• This skill does not track shared people from the Find My People tab.
• Some accessories may return location: null or stale data.
• Family device visibility depends on Find My / Family Sharing state.

Scripts

• scripts/findmy.sh is the main wrapper for username storage, auth, device list, and device show
• scripts/state.sh handles deterministic local state storage
• scripts/device-find.py filters devices by case-insensitive substring match
• scripts/person-find.py resolves a person alias/name to the best matching device, preferring iPhone then Watch