Repository navigation
CLI reference
Generated by packaging/scripts/gen-cli-docs.py. Do not hand-edit.
Show the most recent alert deliveries, newest first.
Usage: findplus alerts deliveries [OPTIONS]
| option | default | help |
|---|---|---|
| --limit | 100 | |
| --json | Output JSON. |
Create an alert rule for a place, targeting a group or a single device.
Usage: findplus alerts rules add [OPTIONS]
| option | default | help |
|---|---|---|
| --group | ||
| --device-id | ||
| --place | ||
| --enter | ||
| --exit | ||
| --channel | Repeatable: --channel telegram --channel native. | |
| --cooldown | 30 | |
| --also-notify-members | ||
| --telegram-target | Repeatable: limit Telegram delivery to this saved chat id. Omit for every saved target. | |
| --telegram-all | Send to every saved Telegram target (the default). |
Edit an alert rule; only the given options change.
Usage: findplus alerts rules edit [OPTIONS]
| option | default | help |
|---|---|---|
| --name | Rename the rule. | |
| --place | ||
| --enter | ||
| --exit | ||
| --channel | Repeatable; passing any --channel replaces the whole set. | |
| --cooldown | ||
| --enable | ||
| --telegram-target | Repeatable: limit Telegram delivery to this saved chat id. | |
| --telegram-all | Switch back to every saved Telegram target. |
List every alert rule.
Usage: findplus alerts rules list [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Output JSON. |
Delete an alert rule.
Usage: findplus alerts rules remove [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Confirm removal. |
Remove the stored Telegram bot token and chat id.
Usage: findplus alerts telegram-clear [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Confirm clearing the Telegram configuration. |
Connect a Telegram bot: verify the token, then wait for the user to message it.
Usage: findplus alerts telegram-setup [OPTIONS]
| option | default | help |
|---|---|---|
| --token, -t | Bot token (prompted if omitted). | |
| --wait | 120 | Seconds to wait for a message. |
Replace the Telegram target list: chat ids or @usernames, comma separated.
Usage: findplus alerts telegram-targets [OPTIONS]
Send a test alert through the given channel.
Usage: findplus alerts test [OPTIONS]
| option | default | help |
|---|---|---|
| --channel |
Remove the stored webhook URL and secret.
Usage: findplus alerts webhook-clear [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Confirm clearing the webhook configuration. |
Configure the webhook channel.
Usage: findplus alerts webhook-set [OPTIONS]
| option | default | help |
|---|---|---|
| --secret, -s | HMAC signing secret (optional). |
Remove the stored WhatsApp phone and apikey.
Usage: findplus alerts whatsapp clear [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Confirm clearing the WhatsApp configuration. |
Configure the WhatsApp (CallMeBot) channel.
Usage: findplus alerts whatsapp set [OPTIONS]
| option | default | help |
|---|---|---|
| --phone | E.164 phone number, e.g. +34123123123. | |
| --apikey | CallMeBot API key. |
Register an accessory from a pairing --plist export or a --private-key.
Usage: findplus apple add-accessory [OPTIONS]
| option | default | help |
|---|---|---|
| --plist | ||
| --private-key |
List every registered accessory.
Usage: findplus apple list [OPTIONS]
Remove a registered accessory by its device ID.
Usage: findplus apple remove [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Confirm removal. |
Sign in to a provider (Google via Chrome, or Apple interactively).
Usage: findplus auth [OPTIONS]
| option | default | help |
|---|---|---|
| --status | Print sign-in status and exit. | |
| --json | With --status, print JSON instead of a table. | |
| --sign-out | Remove this provider's saved sign-in credential and exit. | |
| --token | Google: sign in in your own Chrome and paste the oauth_token cookie (or set FINDPLUS_OAUTH_TOKEN). | |
| --provider | google-find-hub | Provider to authenticate: google-find-hub or apple-find-my |
Print the value of KEY from config.env, or empty if unset.
Usage: findplus config get [OPTIONS]
Print all KEY=VALUE pairs in config.env.
Usage: findplus config list [OPTIONS]
Print the path to config.env.
Usage: findplus config path [OPTIONS]
Write KEY=VALUE to config.env after validating through Settings.
Usage: findplus config set [OPTIONS]
Remove KEY from config.env.
Usage: findplus config unset [OPTIONS]
Print the current Alembic revision of the database.
Usage: findplus db current [OPTIONS]
Print the absolute path to the SQLite database file.
Usage: findplus db path [OPTIONS]
Run Alembic migrations to head. Safe to run repeatedly (idempotent).
Usage: findplus db upgrade [OPTIONS]
List the trackers Find+ knows about and choose which ones to track.
Usage: findplus devices [OPTIONS]
| option | default | help |
|---|---|---|
| --track | Track this device id (repeatable). | |
| --track-all | Track every device on the account. | |
| --untrack | Stop tracking a device id. | |
| --default | Device the dashboard opens on. | |
| --refresh | Re-query Find Hub for the list before printing it (needs a signed-in account). | |
| --json | Print the device list as JSON. |
List the available Lucide icon ids.
Usage: findplus devices icons [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Output JSON. |
Set a device's label, icon and/or color.
Usage: findplus devices label [OPTIONS]
| option | default | help |
|---|---|---|
| --label | Your own name for this tracker. | |
| --icon | lucide:, letter:, letter, none. | |
| --color | Lowercase #rrggbb. |
Diagnose the installation; with --repair, fix what can be fixed.
Usage: findplus doctor [OPTIONS]
| option | default | help |
|---|---|---|
| --repair | Attempt automatic fixes for repairable checks. | |
| --json | Print machine-readable JSON. |
Export history to CSV, JSON, GPX or KML.
Usage: findplus export [OPTIONS]
| option | default | help |
|---|---|---|
| --format | csv | |
| --day | Single local day, YYYY-MM-DD. | |
| --start | Range start, YYYY-MM-DD. | |
| --end | Range end, YYYY-MM-DD. | |
| --all | Export the entire history. | |
| --device-id | Limit to one device. Omit for all devices. | |
| --group | Export every member's track (never merged). | |
| --output, -o |
Create a new device group.
Usage: findplus groups add [OPTIONS]
| option | default | help |
|---|---|---|
| --color | #27ae60 | |
| --quorum | majority | |
| --cluster-radius | 150 | |
| --stale-after | 90 | |
| --member | Device id; repeatable. |
Update one or more fields of an existing group.
Usage: findplus groups edit [OPTIONS]
| option | default | help |
|---|---|---|
| --name | ||
| --color | ||
| --quorum | ||
| --cluster-radius | ||
| --stale-after |
List group ENTER/EXIT crossings that met quorum.
Usage: findplus groups events [OPTIONS]
| option | default | help |
|---|---|---|
| --group | ||
| --place | ||
| --since | ||
| --until | ||
| --limit | 200 | |
| --format | table |
List every device group.
Usage: findplus groups list [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Output JSON. |
Replace a group's membership (full replace, not merge).
Usage: findplus groups members [OPTIONS]
| option | default | help |
|---|---|---|
| --set | Comma-separated device ids. |
Show live group presence: verdict, note, and a per-device table.
Usage: findplus groups presence [OPTIONS]
| option | default | help |
|---|---|---|
| --window | 60 | |
| --json | Output JSON. |
Delete a group and its membership rows.
Usage: findplus groups remove [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Confirm removal. |
Start the background service: auth check, then discover-and-track, then
Usage: findplus install-service [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Write and load the service files without asking. | |
| --no-open | Do not open the dashboard in a browser. | |
| --program, -P | Path to the daemon executable. The desktop app passes /Applications/Find+.app/Contents/MacOS/findplus-daemon here. | |
| --no-track-all | Discover devices but do not track them. |
Show, then optionally install, the watchdog job.
Usage: findplus install-watchdog [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Skip the confirmation prompt. |
Forgot your PIN? Remove the app lock from this machine.
Usage: findplus lock reset [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Skip the confirmation prompt. |
Start the Find+ MCP server (stdio transport).
Usage: findplus mcp [OPTIONS]
| option | default | help |
|---|---|---|
| --allow-writes | Register write tools (poll, places, groups, lock). | |
| --url | http://127.0.0.1:8647 | Base URL of the local Find+ daemon. |
Open the dashboard in the default browser.
Usage: findplus open [OPTIONS]
Delete the PIN and turn the app lock off.
Usage: findplus pin reset [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Skip the confirmation prompt. |
Save a new place.
Usage: findplus places add [OPTIONS]
| option | default | help |
|---|---|---|
| --lat | Latitude (decimal degrees). | |
| --lon | Longitude (decimal degrees). | |
| --radius | Radius in metres. | |
| --color | #2f80ed | |
| --enter-confirmations | 1 | |
| --exit-confirmations | 2 |
Update one or more fields of an existing place.
Usage: findplus places edit [OPTIONS]
| option | default | help |
|---|---|---|
| --name | ||
| --lat | ||
| --lon | ||
| --radius | ||
| --color | ||
| --enter-confirmations | ||
| --exit-confirmations |
List geofence ENTER/EXIT events.
Usage: findplus places events [OPTIONS]
| option | default | help |
|---|---|---|
| --place | ||
| --device-id | ||
| --since | ||
| --until | ||
| --limit | 200 | |
| --format | table |
List every saved place.
Usage: findplus places list [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Output JSON. |
Delete a place. Requires --yes.
Usage: findplus places remove [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Confirm removal. |
Run a single Find Hub poll immediately.
Usage: findplus poll-now [OPTIONS]
| option | default | help |
|---|---|---|
| --device-id | Poll only this device id (repeatable). Default: every tracked device. |
List installed location providers and whether they are ready to poll.
Usage: findplus providers [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Output as JSON |
Delete history before a date. Dry run unless --yes is given.
Usage: findplus prune [OPTIONS]
| option | default | help |
|---|---|---|
| --before | Delete observations before this local date. | |
| --yes | Actually delete. Without this it is a dry run. |
Forgot your PIN? Remove the app lock from this machine.
Usage: findplus reset-lock [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Skip the confirmation prompt. |
Restart the background service.
Usage: findplus restart [OPTIONS]
Check that this install can start sign-in helpers and has Apple support.
Usage: findplus selfcheck [OPTIONS]
| option | default | help |
|---|---|---|
| --no-apple | Skip the Apple Find My library check. |
Start the local API/UI and (unless disabled) the polling service.
Usage: findplus serve [OPTIONS]
| option | default | help |
|---|---|---|
| --foreground | Run in this terminal (used by the service). | |
| --no-poller | Serve the UI/API without polling Google. | |
| --host | ||
| --port |
Guided first-run setup: sign-in, devices, groups, places, notifications, app lock.
Usage: findplus setup [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Non-interactive: accept every default, skip every optional step. |
Start the background service: auth check, then discover-and-track, then
Usage: findplus start [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Write and load the service files without asking. | |
| --no-open | Do not open the dashboard in a browser. | |
| --program, -P | Path to the daemon executable. The desktop app passes /Applications/Find+.app/Contents/MacOS/findplus-daemon here. | |
| --no-track-all | Discover devices but do not track them. |
Show service, watchdog and daemon status.
Usage: findplus status [OPTIONS]
| option | default | help |
|---|---|---|
| --json | Print machine-readable JSON. |
Stop the background service. Unit files are kept; the next login (or
Usage: findplus stop [OPTIONS]
Set the dashboard theme without opening the UI.
Usage: findplus theme [OPTIONS]
Unload and delete the service and watchdog unit files, and daemon.json.
Usage: findplus uninstall [OPTIONS]
| option | default | help |
|---|---|---|
| --yes | Unload and delete the unit files without asking. |
Print the installed version.
Usage: findplus version [OPTIONS]
| option | default | help |
|---|---|---|
| --check | Check for a newer release on GitHub. |
Check the local API and restart the service if it is not answering.
Usage: findplus watchdog [OPTIONS]
Ask the Find+ app to reload the widget's WidgetKit timelines.
Usage: findplus widget refresh [OPTIONS]
Show or hide the map preview in the large widget.
Usage: findplus widget show-map [OPTIONS]