git404hub

what is findmy-cli fr?

omarshahine/findmy-cli — explained in plain English

Analysis updated 2026-05-18

17GoAudience · developerComplexity · 4/5Setup · hard

tl;dr

A macOS command-line tool that reads Find My people and device locations by screenshotting the Find My app and running OCR on it.

vibe map

mindmap
  root((findmy-cli))
    What it does
      Reads Find My locations
      Screenshots plus OCR
    Tech stack
      Go
      Swift
      Vision framework
    Use cases
      CLI location lookups
      Headless Mac setups
      AI assistant plugin
    Audience
      Developers
      macOS power users

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

what do people make with this?

VIBE 1

Get Find My people and device locations from the command line or as JSON for scripting.

VIBE 2

Run Find My lookups on a headless Mac mini or Mac Studio using a dummy display adapter.

VIBE 3

Wire Find My location lookups into an AI assistant as a Claude Code or OpenClaw plugin.

what's the stack?

GoSwiftmacOS Vision framework

how it stacks up fr

omarshahine/findmy-clicloudpilot-ai/hermeshloolx/hloolmail
Stars171717
LanguageGoGoGo
Setup difficultyhardhardmoderate
Complexity4/54/53/5
Audiencedeveloperops devopsdeveloper

Figures from each repo's GitHub metadata at analysis time.

how do i run it?

Difficulty · hard time til it works · 1h+

Requires macOS with an awake, unlocked display, plus Screen Recording and Accessibility permissions granted and the host process restarted.

in plain english

findmy-cli is a command-line tool that reads location data from Apple's Find My app on macOS. Apple does not provide a public API for Find My locations, and the on-disk cache files are encrypted with keychain-bound keys, so this tool automates the Find My app's graphical interface instead. It captures a screenshot of the app window and uses Apple's built-in Vision framework to read the text through optical character recognition, or OCR. The tool is split into two parts. A small Swift binary called findmy-helper handles the macOS specific tasks, such as taking screenshots, listing windows, and simulating mouse clicks, because the relevant Apple APIs have no direct Go bindings. A Go command-line tool called findmy orchestrates everything, calling the helper and parsing results. Together they can list people and devices from the Find My sidebar, click on a specific entry to reveal a precise address, and output everything as plain text or JSON. Because the tool drives the GUI, the Mac display must be active and unlocked, since a sleeping display causes screenshots to return as solid black. For headless setups such as a Mac mini without a monitor, the README describes connecting an inexpensive dummy display adapter that tricks macOS into activating its window compositor, along with disabling display sleep. Required macOS permissions include Screen Recording and Accessibility, and the terminal process must be fully restarted after granting them. Beyond a standalone CLI, the project also packages the tool as a Homebrew formula, an NPM library, and a plugin for AI assistant systems built on Claude Code and OpenClaw. The project notes that GUI scraping may be outside Apple's terms of service and should be used at your own risk.

prompts (copy fr)

prompt 1
Help me install findmy-cli via Homebrew and grant it the right macOS permissions.
prompt 2
Show me how to run this on a headless Mac using a dummy display adapter.
prompt 3
Explain why my findmy screenshots are coming back black and how to fix it.
prompt 4
Walk me through wiring this up as a Claude Code plugin.

Frequently asked questions

what is findmy-cli fr?

A macOS command-line tool that reads Find My people and device locations by screenshotting the Find My app and running OCR on it.

What language is findmy-cli written in?

Mainly Go. The stack also includes Go, Swift, macOS Vision framework.

How hard is findmy-cli to set up?

Setup difficulty is rated hard, with roughly 1h+ to a first successful run.

Who is findmy-cli for?

Mainly developer.

peek the repo → explain another one

This repo across BitVibe Labs

double-check against the repo, no cap.